@antelopejs/interface-dms-saas 0.4.0 → 0.4.1

package/README.md

@@ -1,95 +1,85 @@
+<div align="center">
+
 # @antelopejs/interface-dms-saas
 
-<div align="center">
-<a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-blue?style=for-the-badge&labelColor=000000"></a>
-<a href="https://discord.gg/sjK28QHrA7"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000" alt="Discord"></a>
-<a href="https://antelopejs.com"><img src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000" alt="Documentation"></a>
+<a href="https://www.npmjs.com/package/@antelopejs/interface-dms-saas"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-dms-saas?style=for-the-badge&labelColor=000000&color=000000"></a>
+<a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/interface-dms-saas?style=for-the-badge&labelColor=000000&color=000000"></a>
+<a href="https://discord.gg/sjK28QHrA7"><img alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
+<a href="https://dms.antelopejs.com/docs/modules/saas/extending"><img alt="Documentation" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
+
+The AntelopeJS interface to extend the DMS SaaS module: billing, plans, registration, workspace pages and lifecycle.
+
 </div>
 
-Public interfaces of the AntelopeJS DMS SaaS module.
+## What it does
 
-A module that extends `@antelopejs/dms-saas` depends on this package rather than
-on the runtime, and imports the extension points from it:
+- Adds invoice line items, reads customer balances and previews the upcoming invoice.
+- Builds plan projections and catalogues, and normalizes prices.
+- Extends registration and the provisioning of a new workspace.
+- Adds workspace settings categories and blocks to the tenant billing page.
+- Listens to workspace lifecycle events and operator actions, and exposes the canonical SaaS tables and models (`/db`).
 
-| Subpath | Surface |
-| --- | --- |
-| `@antelopejs/interface-dms-saas` | every extension point except `db`: billing, data API, pages, plans, provisioning and registration flat, plus the `invoiceLineItems` and `workspaceLifecycle` namespaces |
-| `@antelopejs/interface-dms-saas/billing` | customer balance, upcoming invoice preview and complimentary subscription state |
-| `@antelopejs/interface-dms-saas/data-api` | hidden-value data API filters |
-| `@antelopejs/interface-dms-saas/db` | canonical SaaS tables and data models |
-| `@antelopejs/interface-dms-saas/hidden-filter` | the `HiddenStringFilter` decorator on its own |
-| `@antelopejs/interface-dms-saas/invoice-line-items` | provider registration, line item types, line key helpers |
-| `@antelopejs/interface-dms-saas/page-definitions` | page and module ids, slugs and descriptors |
-| `@antelopejs/interface-dms-saas/pages` | workspace settings category and tenant billing page extensions |
-| `@antelopejs/interface-dms-saas/plans` | plan projections, catalog builder, and price normalization |
-| `@antelopejs/interface-dms-saas/provisioning` | provisioning hook payload |
-| `@antelopejs/interface-dms-saas/registration` | public registration capture limits |
-| `@antelopejs/interface-dms-saas/workspace-lifecycle` | workspace lifecycle events and operator actions |
-
-Two of those surfaces reach the root entry as namespaces rather than flat
-re-exports, because each exposes an `internal` proxy namespace and two
-`internal` names cannot coexist in one barrel:
-
-```ts
+A module that extends [`@antelopejs/dms-saas`](https://www.npmjs.com/package/@antelopejs/dms-saas) depends on this package, never on the runtime.
+
+## Install
+
+```bash
+pnpm add @antelopejs/interface-dms-saas
+```
+
+## Quick start
+
+The root entry holds every extension point except `db`, with `invoiceLineItems` and `workspaceLifecycle` as namespaces:
+
+```ts docs-check
 import { invoiceLineItems, workspaceLifecycle } from "@antelopejs/interface-dms-saas";
 
-invoiceLineItems.RegisterInvoiceLineItemsProvider(/* … */);
+export const usageKey = invoiceLineItems.buildInvoiceLineKey("example.compute", "minutes");
+export const isProvisioningCommitted = workspaceLifecycle.IsWorkspaceProvisioningCommitted;
 ```
 
-Their own subpaths stay the direct route to the same symbols. `./db` is the one
-surface the root entry leaves out: importing it registers the SaaS tables, and a
-consumer that only wants types should not pay for that.
-
-Subpaths resolve through the `exports` map only, so consumers must compile with
-`moduleResolution` set to `bundler`, `node16` or `nodenext`; the legacy `node`
-(node10) mode is not supported.
-
-This package is released on its own workflow and must be published before the
-runtime module: `@antelopejs/dms-saas` depends on it through
-`>=<interface version> <0.<minor + 1>.0`, a range that only resolves once this
-package is released. The runtime implements this interface, so it caps the range
-below the next minor: a breaking minor of this package never reaches an older
-dms-saas.
-
-## Writing plans
-
-A module may seed plans straight into the `db` plan table. It leaves
-`Plan.paymentProviderRefs` empty on creation and never rewrites it: dms-saas
-links every plan billed through Stripe to a matching Stripe product and price,
-at startup and whenever the plan is offered or billed, and records what it
-synced in `paymentProviderRefs.stripeSyncedTerms`. See
-[Plans and Stripe](../dms-saas/README.md#plans-and-stripe).
-
-## Upgrading
-
-### Tenant billing page anchors
-
-The plan, next invoice, payment method and money-back cards of the tenant
-billing page now share a two-column grid (`overview`), so `planCard`,
-`paymentMethod` and `refundButton` are no longer top-level fields of the page.
-The names in `tenantBillingPage.components` are unchanged, and
-`RegisterTenantBillingPageExtension` maps each one to its position through
-`tenantBillingPageAnchorPaths`: a block registered after `planCard` still lands
-right under the plan card, in its column. Upgrade this package together with
-`@antelopejs/dms-saas`, since an earlier build of it anchors on the old
-top-level fields, which the DMS no longer finds (the block is then appended at
-the end of the page). Code that anchors with the DMS's own
-`@RegisterPageExtension` must pass the path, as in
-`.after(tenantBillingPageAnchorPaths.planCard)`.
-
-The permission ids of those four cards follow their position
-(`settings.workspace.billing.overview.plan.current.planCard`, and so on), so a
-plan or role granting them needs the new ids.
-
-### Rows written by earlier builds
-
-The data contract no longer tolerates rows that predate the current fields:
-`TenantSubscription.isComplimentary` is a required boolean and
-`isComplimentarySubscription` only returns `true` for `isComplimentary: true`,
-`InvoiceModel.getAllInvoices` only matches `documentType: "invoice"`,
-`WebhookResult` no longer includes `failed`, `TenantSubscription.paidUsagePeriods`
-is a required array that alone decides billable usage, and `revision` is
-required on `TenantSubscription`, `Segment`, `UserSegment`, `PlanMigration` and
-`StripeWebhookEvent`, whose revision-fenced writes refuse a row without one.
-Fix such rows before upgrading, as described in the
-[`@antelopejs/dms-saas` upgrade notes](../dms-saas/README.md#upgrading).
+Use the [entry-point reference](./docs/1.index.md#entry-points) for supported
+subpaths. Importing `/db` registers SaaS tables; it is not a side-effect-free
+types barrel. After direct subscription writes, call
+[`RecomputeTenantBillingState`](./docs/2.billing.md#recomputetenantbillingstate)
+to refresh derived billing and workspace directory state.
+
+A module may seed plans straight into the `db` plan table: it leaves `Plan.paymentProviderRefs` empty and never rewrites it, since dms-saas links every billed plan to Stripe itself. See [Plans and Stripe](https://dms.antelopejs.com/docs/modules/saas/stripe#plans-and-stripe).
+
+## Compatibility
+
+The implementation is `@antelopejs/dms-saas >=0.6.0`. The interface declares these dependencies:
+
+<!-- docs-compat: ./package.json#dependencies -->
+
+| Package | Range |
+| --- | --- |
+| `@antelopejs/interface-data-api` | `>=0.2.2 <1.0.0` |
+| `@antelopejs/interface-dms` | `>=0.7.2 <1.0.0` |
+
+Peer dependencies:
+
+<!-- docs-compat: ./package.json#peerDependencies -->
+
+| Package | Range |
+| --- | --- |
+| `@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` |
+
+Subpaths resolve through the `exports` map only: compile consumers with `moduleResolution` set to `bundler`, `node16` or `nodenext`. Upgrade this package together with `@antelopejs/dms-saas`; the [upgrade notes](https://dms.antelopejs.com/docs/modules/saas/faq#upgrading) cover the tenant billing page anchors and the rows written by earlier builds.
+
+## Documentation
+
+- [Consumer reference](./docs/1.index.md): billing, usage, lifecycle, pages, plans and database boundaries
+- [Extending the SaaS module](https://dms.antelopejs.com/docs/modules/saas/extending): every extension point with examples
+- [Stripe](https://dms.antelopejs.com/docs/modules/saas/stripe)
+- [SaaS module guide](https://dms.antelopejs.com/docs/modules/saas)
+
+## Contributing
+
+This package lives in the [`AntelopeJS/dms-saas`](https://github.com/AntelopeJS/dms-saas) pnpm workspace, next to the module that implements it. Read [CONTRIBUTING.md](https://github.com/AntelopeJS/dms-saas/blob/main/CONTRIBUTING.md) and the [repository README](https://github.com/AntelopeJS/dms-saas#contributing) for the development commands. Release this package on its own workflow before the module that implements it.
+
+## License
+
+[Apache-2.0](./LICENSE)

package/dist/db/models/billingSettings.model.d.ts

@@ -12,6 +12,7 @@ declare const BillingSettingsModel_base: {
         delete(id: string): Promise<number>;
     };
     readonly schemaName: string;
+    readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<BillingSettings>;
     fromPlainData(obj: any): BillingSettings;
     fromDatabase(obj: any): BillingSettings | undefined;
     toDatabase(obj: any): Record<string, any>;

package/dist/db/models/creditNotes.model.d.ts

@@ -13,6 +13,7 @@ declare const CreditNoteModel_base: {
         delete(id: string): Promise<number>;
     };
     readonly schemaName: string;
+    readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<CreditNote>;
     fromPlainData(obj: any): CreditNote;
     fromDatabase(obj: any): CreditNote | undefined;
     toDatabase(obj: any): Record<string, any>;

package/dist/db/models/features.model.d.ts

@@ -12,6 +12,7 @@ declare const FeatureModel_base: {
         delete(id: string): Promise<number>;
     };
     readonly schemaName: string;
+    readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<Feature>;
     fromPlainData(obj: any): Feature;
     fromDatabase(obj: any): Feature | undefined;
     toDatabase(obj: any): Record<string, any>;

package/dist/db/models/invoices.model.d.ts

@@ -13,6 +13,7 @@ declare const InvoiceModel_base: {
         delete(id: string): Promise<number>;
     };
     readonly schemaName: string;
+    readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<Invoice>;
     fromPlainData(obj: any): Invoice;
     fromDatabase(obj: any): Invoice | undefined;
     toDatabase(obj: any): Record<string, any>;

package/dist/db/models/legalDocuments.model.d.ts

@@ -12,6 +12,7 @@ declare const LegalDocumentsModel_base: {
         delete(id: string): Promise<number>;
     };
     readonly schemaName: string;
+    readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<LegalDocuments>;
     fromPlainData(obj: any): LegalDocuments;
     fromDatabase(obj: any): LegalDocuments | undefined;
     toDatabase(obj: any): Record<string, any>;

package/dist/db/models/planMigrations.model.d.ts

@@ -13,6 +13,7 @@ declare const PlanMigrationModel_base: {
         delete(id: string): Promise<number>;
     };
     readonly schemaName: string;
+    readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<PlanMigration>;
     fromPlainData(obj: any): PlanMigration;
     fromDatabase(obj: any): PlanMigration | undefined;
     toDatabase(obj: any): Record<string, any>;

package/dist/db/models/plans.model.d.ts

@@ -16,6 +16,7 @@ declare const PlanModel_base: {
         delete(id: string): Promise<number>;
     };
     readonly schemaName: string;
+    readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<Plan>;
     fromPlainData(obj: any): Plan;
     fromDatabase(obj: any): Plan | undefined;
     toDatabase(obj: any): Record<string, any>;

package/dist/db/models/platformNotes.model.d.ts

@@ -22,6 +22,7 @@ declare const PlatformNoteModel_base: {
         delete(id: string): Promise<number>;
     };
     readonly schemaName: string;
+    readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<PlatformNote>;
     fromPlainData(obj: any): PlatformNote;
     fromDatabase(obj: any): PlatformNote | undefined;
     toDatabase(obj: any): Record<string, any>;

package/dist/db/models/refunds.model.d.ts

@@ -12,6 +12,7 @@ declare const RefundModel_base: {
         delete(id: string): Promise<number>;
     };
     readonly schemaName: string;
+    readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<Refund>;
     fromPlainData(obj: any): Refund;
     fromDatabase(obj: any): Refund | undefined;
     toDatabase(obj: any): Record<string, any>;

package/dist/db/models/segments.model.d.ts

@@ -18,6 +18,7 @@ declare const SegmentModel_base: {
         delete(id: string): Promise<number>;
     };
     readonly schemaName: string;
+    readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<Segment>;
     fromPlainData(obj: any): Segment;
     fromDatabase(obj: any): Segment | undefined;
     toDatabase(obj: any): Record<string, any>;

package/dist/db/models/stripeWebhookEvents.model.d.ts

@@ -13,6 +13,7 @@ declare const StripeWebhookEventModel_base: {
         delete(id: string): Promise<number>;
     };
     readonly schemaName: string;
+    readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<StripeWebhookEvent>;
     fromPlainData(obj: any): StripeWebhookEvent;
     fromDatabase(obj: any): StripeWebhookEvent | undefined;
     toDatabase(obj: any): Record<string, any>;

package/dist/db/models/tenantBillingInfo.model.d.ts

@@ -12,6 +12,7 @@ declare const TenantBillingInfoModel_base: {
         delete(id: string): Promise<number>;
     };
     readonly schemaName: string;
+    readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<TenantBillingInfo>;
     fromPlainData(obj: any): TenantBillingInfo;
     fromDatabase(obj: any): TenantBillingInfo | undefined;
     toDatabase(obj: any): Record<string, any>;

package/dist/db/models/tenantBillingState.model.d.ts

@@ -12,6 +12,7 @@ declare const TenantBillingStateModel_base: {
         delete(id: string): Promise<number>;
     };
     readonly schemaName: string;
+    readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<TenantBillingState>;
     fromPlainData(obj: any): TenantBillingState;
     fromDatabase(obj: any): TenantBillingState | undefined;
     toDatabase(obj: any): Record<string, any>;

package/dist/db/models/tenantSubscriptions.model.d.ts

@@ -14,6 +14,7 @@ declare const TenantSubscriptionModel_base: {
         delete(id: string): Promise<number>;
     };
     readonly schemaName: string;
+    readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<TenantSubscription>;
     fromPlainData(obj: any): TenantSubscription;
     fromDatabase(obj: any): TenantSubscription | undefined;
     toDatabase(obj: any): Record<string, any>;

package/dist/db/models/trialConsumptions.model.d.ts

@@ -12,6 +12,7 @@ declare const TrialConsumptionModel_base: {
         delete(id: string): Promise<number>;
     };
     readonly schemaName: string;
+    readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<TrialConsumption>;
     fromPlainData(obj: any): TrialConsumption;
     fromDatabase(obj: any): TrialConsumption | undefined;
     toDatabase(obj: any): Record<string, any>;

package/dist/db/models/userSegments.model.d.ts

@@ -14,6 +14,7 @@ declare const UserSegmentModel_base: {
         delete(id: string): Promise<number>;
     };
     readonly schemaName: string;
+    readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<UserSegment>;
     fromPlainData(obj: any): UserSegment;
     fromDatabase(obj: any): UserSegment | undefined;
     toDatabase(obj: any): Record<string, any>;

package/dist/db/tables/billingSettings.table.d.ts

@@ -3,7 +3,7 @@ export declare const billingSettingsTableName = "billing_settings";
 export declare const BILLING_SETTINGS_SINGLETON_ID = "singleton";
 export declare const DEFAULT_AUTO_SUSPEND_DELAY_DAYS = 14;
 export declare const DEFAULT_STRIPE_TAX_CODE = "txcd_10000000";
-export declare const DEFAULT_MAX_FREE_WORKSPACES_PER_CARD = 1;
+export declare const DEFAULT_MAX_FREE_WORKSPACES_PER_CARD = 0;
 export declare const DEFAULT_DATA_RETENTION_DAYS = 30;
 export declare const REFUND_PRORATA_MODES: readonly ["full", "prorated"];
 export type RefundProrataMode = (typeof REFUND_PRORATA_MODES)[number];

package/dist/db/tables/billingSettings.table.js

@@ -16,7 +16,7 @@ exports.billingSettingsTableName = "billing_settings";
 exports.BILLING_SETTINGS_SINGLETON_ID = "singleton";
 exports.DEFAULT_AUTO_SUSPEND_DELAY_DAYS = 14;
 exports.DEFAULT_STRIPE_TAX_CODE = "txcd_10000000";
-exports.DEFAULT_MAX_FREE_WORKSPACES_PER_CARD = 1;
+exports.DEFAULT_MAX_FREE_WORKSPACES_PER_CARD = 0;
 exports.DEFAULT_DATA_RETENTION_DAYS = 30;
 exports.REFUND_PRORATA_MODES = ["full", "prorated"];
 let BillingSettings = class BillingSettings extends interface_database_decorators_1.Table {

package/docs/1.index.md

@@ -0,0 +1,47 @@
+---
+title: SaaS interface
+description: Supported backend imports and side-effect boundaries for modules extending DMS SaaS.
+---
+
+# SaaS interface
+
+Consumers depend on `@antelopejs/interface-dms-saas`, not the runtime's private services or page controllers. Load `@antelopejs/dms-saas` in the same AntelopeJS project for functions that need an implementation. Compile with `moduleResolution: "bundler"`, `"node16"` or `"nodenext"` so subpaths resolve through the package's exports map.
+
+## Entry points
+
+| Import after `@antelopejs/interface-dms-saas` | Contract |
+| --- | --- |
+| Root | Billing, data API, pages, plans, provisioning and registration exports; `invoiceLineItems` and `workspaceLifecycle` namespaces |
+| `/billing` | [Balances, previews and billing-state recomputation](./2.billing.md) |
+| `/invoice-line-items` | [Usage providers, line types and key helpers](./3.lifecycle-and-usage.md#invoice-line-items) |
+| `/workspace-lifecycle` | [Durable lifecycle consumers and provisioning gate](./3.lifecycle-and-usage.md#workspace-lifecycle) |
+| `/provisioning`, `/registration` | [Provisioning payload and registration limits](./3.lifecycle-and-usage.md#registration-and-provisioning) |
+| `/pages`, `/page-definitions` | [Page descriptors and extension registration](./4.pages-plans-data.md#page-extensions) |
+| `/plans` | [Plan projections, localization and pricing helpers](./4.pages-plans-data.md#plan-helpers) |
+| `/data-api`, `/hidden-filter` | [HiddenStringFilter](./4.pages-plans-data.md#hiddenstringfilter) |
+| `/db`, `/db/models`, `/db/tables` | Canonical SaaS models and table classes; see the data boundary below |
+
+`invoiceLineItems` and `workspaceLifecycle` are namespaces at the root, not flat exports. Use their direct subpaths for individual functions. Their `internal` proxy namespaces are implementation plumbing, not consumer APIs.
+
+```ts docs-check
+import { invoiceLineItems, workspaceLifecycle } from "@antelopejs/interface-dms-saas";
+
+export const usageKey = invoiceLineItems.buildInvoiceLineKey("example.compute", "minutes");
+
+export async function mayProvision(tenantId: string): Promise<boolean> {
+  // Errors propagate: unavailable storage must not grant eligibility.
+  return workspaceLifecycle.IsWorkspaceProvisioningCommitted(tenantId);
+}
+```
+
+## Database imports have side effects
+
+The root does not re-export `db`. Importing `/db` registers the canonical SaaS tables; do not create duplicate table definitions or load the runtime's registration graph to reach them. Prefer `import type` when only a type is needed. The root also exports plan helpers that import database values, so do not assume that a root value import avoids all transitive table registration. Narrow subpaths express which contract the consumer needs.
+
+Database exports are persistence primitives, not an authorization or billing-service API. Use tenant-scoped models with the correct tenant, and keep direct writes in trusted import/seed code. Direct writes do not automatically perform all Stripe, lifecycle, cache and directory work of the runtime's normal operations.
+
+After seeding or importing subscription records, call [RecomputeTenantBillingState](./2.billing.md#recomputetenantbillingstate) for each affected tenant once writes finish. This republishes derived billing and directory state; it does not make an arbitrary direct write equivalent to a normal billing operation. When seeding plans, leave `Plan.paymentProviderRefs` empty and never overwrite the runtime's Stripe linkage. See the [plan and Stripe guide](/docs/modules/saas/stripe#plans-and-stripe).
+
+`workspaceSettingsCategory` belongs to `@antelopejs/interface-dms/page`, not this package. There is no SaaS `GetWorkspaceSettingsCategory` export. Use `/pages` for SaaS billing and platform-workspace extension anchors.
+
+The [runtime guide](/docs/modules/saas/extending) covers installation, public screens, UI integration and examples. These pages define the backend consumer contracts.

package/docs/2.billing.md

@@ -0,0 +1,66 @@
+---
+title: Billing
+description: Authorized customer balances and invoice previews, and republishing derived billing state after direct writes.
+---
+
+# Billing
+
+Import these functions and types from `@antelopejs/interface-dms-saas/billing` or the package root.
+
+## GetTenantCustomerBalance
+
+`GetTenantCustomerBalance(scope: TenantCustomerBalanceScope): Promise<TenantCustomerBalance>` takes `{ tenantId: string, userId: string }` from a trusted authentication boundary. It requires membership and a successful tenant access gate; it rejects unauthorized callers with 403. It does not trust a supplied user ID as proof of authentication.
+
+| Result | Fields |
+| --- | --- |
+| `AvailableTenantCustomerBalance` | `status: "available"`, `balanceMinorUnits: number`, `currency: string` |
+| `AbsentTenantCustomerBalance` | `status: "absent"`, `reason: TenantCustomerBalanceAbsenceReason`, `balanceMinorUnits: null`, `currency: null` |
+
+Amounts are Stripe minor units: negative means customer credit, positive means money owed, and zero means settled. Currency is uppercase ISO 4217. Absence reasons are `complimentary`, `customer_not_configured`, `customer_deleted`, and `currency_unavailable`. Stripe read failures reject with 502 and `saas.errors.billing.customer_balance_provider_unavailable`; they are not an absent balance. This call does not charge or refund the customer.
+
+`isComplimentarySubscription(subscription: ComplimentarySubscriptionState | null | undefined): boolean` is a synchronous helper. `ComplimentarySubscriptionState` has `isComplimentary?: boolean | null`; only an explicit `true` returns true. A free plan alone is not the complimentary marker.
+
+## GetUpcomingInvoicePreview
+
+`GetUpcomingInvoicePreview(scope: UpcomingInvoicePreviewScope): Promise<UpcomingInvoicePreview>` uses the same `{ tenantId, userId }` scope and authorization checks. Stripe failures become an `unavailable` result rather than an invented total; authentication, implementation availability or local storage failures can still reject.
+
+| `status` | Result type and reason |
+| --- | --- |
+| `available` | `AvailableUpcomingInvoicePreview`: Stripe priced the next invoice |
+| `absent` | `AbsentUpcomingInvoicePreview`: `complimentary`, `free_plan`, `customer_not_configured`, `subscription_not_configured`, or `no_upcoming_invoice` |
+| `unavailable` | `UnavailableUpcomingInvoicePreview`: `stripe_not_configured`, `tax_not_configured`, `tax_location_invalid`, `tax_location_required`, `tax_calculation_failed`, `usage_unavailable`, or `provider_error` |
+
+Both non-available variants have `reason` and `computedAt: string`. The corresponding exported unions are `UpcomingInvoicePreviewAbsenceReason` and `UpcomingInvoicePreviewUnavailableReason`.
+
+An available preview includes these fields. All amounts are integers in the minor units of its uppercase `currency`; all dates are ISO 8601 strings.
+
+| Fields | Type and meaning |
+| --- | --- |
+| `subtotalMinorUnits`, `totalExcludingTaxMinorUnits`, `taxMinorUnits`, `totalMinorUnits`, `amountDueMinorUnits` | `number`: subtotal before discounts/tax; total after discounts before tax; tax; tax-inclusive total; amount after customer balance |
+| `lines`, `hasMoreLines` | `UpcomingInvoiceLine[]`, `boolean`: line page and truncation flag; totals remain complete |
+| `taxes`, `taxCountry`, `isReverseCharge` | `UpcomingInvoiceTax[]`, `string \| null`, `boolean` |
+| `periodStart`, `periodEnd`, `billingDate`, `computedAt` | `string`: cycle bounds, issue date and computation time |
+| `usageThrough` | `string \| null`: end of quoted usage, null without usage lines |
+
+`UpcomingInvoiceLine` has `kind: UpcomingInvoiceLineKind` (`subscription`, `usage`, or `invoice_item`), `description: string | null`, `amountMinorUnits: number`, `taxMinorUnits: number`, `quantity: number | null`, `periodStart: string`, `periodEnd: string`, `isProration: boolean`, `usageLineKey: string | null`, and `productId: string | null`. Usage keys are `<provider id>:<key>`; other line kinds have a null usage key.
+
+`UpcomingInvoiceTax` has `amountMinorUnits: number`, `taxableAmountMinorUnits: number | null`, `isInclusive: boolean`, `ratePercentage: number | null`, `isReverseCharge: boolean`, and nullable string fields `country`, `taxType`, `displayName`, `jurisdiction`, and `taxabilityReason`. A reverse charge can produce zero tax with `isReverseCharge: true`.
+
+The preview calls usage providers with `isPreview: true` and can populate a tenant-level shared database cache. It never creates an invoice or charges quoted lines. Usage covers the running cycle so far, not its final total; display `computedAt`. A missing payment method does not itself prevent previewing. Cache lifetime, invalidation and Stripe read timeouts are [runtime configuration](/docs/modules/saas/extending#upcoming-invoice-preview).
+
+## RecomputeTenantBillingState
+
+`RecomputeTenantBillingState(tenantId: string): Promise<void>` republishes the tenant's billing state and workspace directory fields, including plan, seats, MRR, renewal and owner, from current records. Call it after a seed or import finishes direct writes. Normal runtime billing operations already do this.
+
+This is a trusted administrative call with no user scope or membership check. Authorize the tenant before invoking it. It writes derived database state, does not mutate the Stripe subscription, and does not replace lifecycle delivery or preview-cache invalidation. Deleted directory rows and subscriptions whose deletion has started are left alone. Storage errors propagate; repeated concurrent-publication conflicts reject after bounded retries. Await completion and report failures instead of displaying stale directory state as current.
+
+```ts docs-check
+import { RecomputeTenantBillingState } from "@antelopejs/interface-dms-saas/billing";
+
+// Invoke only after the import has committed all rows for these authorized tenants.
+export async function refreshImportedTenants(tenantIds: readonly string[]): Promise<void> {
+  for (const tenantId of new Set(tenantIds)) {
+    await RecomputeTenantBillingState(tenantId);
+  }
+}
+```

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.4.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.2.0 <1.0.0",
-    "@antelopejs/interface-dms": ">=0.5.5 <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": {}