@happyvertical/smrt-users 0.51.31 → 0.51.33

package/dist/collections/AccessRequestCollection.d.ts

@@ -1,3 +1,13 @@
+/**
+ * AccessRequestCollection — query helpers for {@link AccessRequest} records.
+ *
+ * This is the low-level data accessor. Lifecycle orchestration (the public-safe
+ * create path, the state machine, capability gating, events, and graduation
+ * into a `User`) lives in {@link AccessRequestService} — prefer the service for
+ * application code.
+ *
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { AccessRequest } from '../models/AccessRequest.js';
 import { AccessRequestStatus } from '../types/index.js';

package/dist/collections/CliAuthApproveLimitCollection.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Atomic shared-storage limiter for terminal device-code approvals.
+ *
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { UsersCliAuthApproveLimit } from '../models/CliAuthApproveLimit.js';
 export type CliAuthApproveReservation = {

package/dist/collections/CliAuthRequestCollection.d.ts

@@ -1,3 +1,8 @@
+/**
+ * UsersCliAuthRequestCollection — lookups for the device-code grant flow.
+ *
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { UsersCliAuthRequest } from '../models/CliAuthRequest.js';
 export interface ApprovePendingCliAuthRequestInput {

package/dist/collections/GroupCollection.d.ts

@@ -1,3 +1,7 @@
+/**
+ * GroupCollection - Collection manager for Group objects
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { Group } from '../models/Group.js';
 /**

package/dist/collections/GroupMemberCollection.d.ts

@@ -1,3 +1,7 @@
+/**
+ * GroupMemberCollection - Collection manager for GroupMember objects
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { GroupMember } from '../models/GroupMember.js';
 /**

package/dist/collections/GroupRoleCollection.d.ts

@@ -1,3 +1,7 @@
+/**
+ * GroupRoleCollection - Collection manager for GroupRole objects
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { GroupRole } from '../models/GroupRole.js';
 /**

package/dist/collections/MagicLinkTokenCollection.d.ts

@@ -1,3 +1,10 @@
+/**
+ * MagicLinkTokenCollection - Collection manager for MagicLinkToken objects
+ *
+ * Provides nonce lookup and single-use enforcement for magic link authentication.
+ *
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { UsersMagicLinkToken } from '../models/MagicLinkToken.js';
 /**

package/dist/collections/MembershipCollection.d.ts

@@ -1,3 +1,7 @@
+/**
+ * MembershipCollection - Collection manager for Membership objects
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { Membership } from '../models/Membership.js';
 import { MembershipStatus } from '../types/index.js';

package/dist/collections/MembershipOverrideCollection.d.ts

@@ -1,3 +1,7 @@
+/**
+ * MembershipOverrideCollection - Collection manager for MembershipOverride objects
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { MembershipOverride } from '../models/MembershipOverride.js';
 import { OverrideEffect } from '../types/index.js';

package/dist/collections/PermissionCollection.d.ts

@@ -1,3 +1,7 @@
+/**
+ * PermissionCollection - Collection manager for Permission objects
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { Permission } from '../models/Permission.js';
 /**

package/dist/collections/ResourceGrantCollection.d.ts

@@ -1,3 +1,4 @@
+/** Collection helpers for exact resource grants. @packageDocumentation */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { ResourceGrant } from '../models/ResourceGrant.js';
 export declare class ResourceGrantCollection extends SmrtCollection<ResourceGrant> {

package/dist/collections/RoleCollection.d.ts

@@ -1,6 +1,10 @@
+/**
+ * RoleCollection - Collection manager for Role objects
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { Role } from '../models/Role.js';
-import { RolePermissionPatternMatrix, SeedRolePermissionsOptions } from './RolePermissionCollection.js';
+import type { RolePermissionPatternMatrix, SeedRolePermissionsOptions } from './RolePermissionCollection.js';
 export interface SeedSystemRolesOptions extends Omit<SeedRolePermissionsOptions, 'catalog'> {
     permissionMatrix?: RolePermissionPatternMatrix;
     seedPermissions?: boolean;

package/dist/collections/RolePermissionCollection.d.ts

@@ -1,7 +1,11 @@
+/**
+ * RolePermissionCollection - Collection manager for RolePermission objects
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { RolePermission } from '../models/RolePermission.js';
-import { PermissionCatalog } from '../services/PermissionCatalogService.js';
-import { DefaultRoleSlug } from '../types/index.js';
+import { type PermissionCatalog } from '../services/PermissionCatalogService.js';
+import { type DefaultRoleSlug } from '../types/index.js';
 export type RolePermissionPatternMatrix = Partial<Record<string, readonly string[]>>;
 export interface SeedRolePermissionsOptions {
     catalog?: PermissionCatalog;

package/dist/collections/SessionCollection.d.ts

@@ -1,3 +1,7 @@
+/**
+ * SessionCollection - Collection manager for Session objects
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { Session } from '../models/Session.js';
 /**

package/dist/collections/TenantCollection.d.ts

@@ -1,3 +1,7 @@
+/**
+ * TenantCollection - Collection manager for Tenant objects
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { Tenant } from '../models/Tenant.js';
 import { TenantHierarchyError } from '../models/tenant-hierarchy.js';

package/dist/collections/TenantIntegrationCollection.d.ts

@@ -1,5 +1,10 @@
+/**
+ * TenantIntegrationCollection - accessors for tenant integration rows.
+ *
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
-import { TenantIntegration, TenantIntegrationProvider } from '../models/TenantIntegration.js';
+import { TenantIntegration, type TenantIntegrationProvider } from '../models/TenantIntegration.js';
 export declare class TenantIntegrationCollection extends SmrtCollection<TenantIntegration> {
     static readonly _itemClass: typeof TenantIntegration;
     listForTenant(tenantId: string): Promise<TenantIntegration[]>;

package/dist/collections/TenantPermissionOverrideCollection.d.ts

@@ -1,3 +1,7 @@
+/**
+ * TenantPermissionOverrideCollection - Collection manager for TenantPermissionOverride objects
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
 import { TenantPermissionOverride } from '../models/TenantPermissionOverride.js';
 import { TenantPermissionEffect } from '../types/index.js';

package/dist/collections/UserCollection.d.ts

@@ -1,6 +1,10 @@
+/**
+ * UserCollection - Collection manager for User objects
+ * @packageDocumentation
+ */
 import { SmrtCollection } from '@happyvertical/smrt-core';
-import { OidcIdentity, Profile } from '@happyvertical/smrt-profiles';
-import { getDatabase } from '@happyvertical/sql';
+import { OidcIdentity, type Profile } from '@happyvertical/smrt-profiles';
+import type { getDatabase } from '@happyvertical/sql';
 import { User } from '../models/User.js';
 import { UserStatus } from '../types/index.js';
 type DatabaseInterface = Awaited<ReturnType<typeof getDatabase>>;

package/dist/index.d.ts

@@ -1,3 +1,59 @@
+/**
+ * @happyvertical/smrt-users
+ *
+ * Multi-tenant user management for the SMRT framework.
+ * Provides users, tenants, roles, permissions, and groups.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   User,
+ *   UserCollection,
+ *   Tenant,
+ *   TenantCollection,
+ *   Role,
+ *   RoleCollection,
+ *   Permission,
+ *   PermissionCollection,
+ *   Membership,
+ *   MembershipCollection,
+ *   PermissionResolver,
+ *   UserStatus,
+ *   MembershipStatus,
+ * } from '@happyvertical/smrt-users';
+ *
+ * // Create collections
+ * const users = await UserCollection.create({
+ *   persistence: { type: 'sql', url: 'app.db' }
+ * });
+ *
+ * // Seed system roles
+ * const roles = await RoleCollection.create({ persistence: { type: 'sql', url: 'app.db' } });
+ * await roles.seedSystemRoles();
+ *
+ * // Resolve permissions
+ * const resolver = await PermissionResolver.create({ persistence: { type: 'sql', url: 'app.db' } });
+ * const hasAccess = await resolver.hasPermission(user.id, tenant.id, 'articles.create');
+ *
+ * // Sync manifest-derived permissions into the Permission table
+ * const syncResult = await syncPermissionCatalog({
+ *   db: { type: 'postgres', url: process.env.DATABASE_URL! }
+ * });
+ * console.log(syncResult.created);
+ *
+ * // Generate or apply Postgres RLS policies
+ * const sql = generatePostgresPermissionSql({
+ *   db: { type: 'postgres', url: process.env.DATABASE_URL! }
+ * });
+ * console.log(sql.targets);
+ * await applyPostgresPermissionPolicies({
+ *   db: { type: 'postgres', url: process.env.DATABASE_URL! }
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+import './__smrt-register__.js';
 export { AccessRequestCollection, type CliAuthApproveReservation, CliAuthRequestCollection, type CreateChildTenantOptions, type CreateSessionOptions, DEFAULT_ROLE_PERMISSION_PATTERNS, type GetOrCreateFromOidcOptions, GroupCollection, GroupMemberCollection, GroupRoleCollection, MagicLinkTokenCollection, MembershipCollection, MembershipOverrideCollection, type NormalizedOidcClaims, type OidcClaims, type OidcIdentityResult, type OidcProfileOwnerAuthorization, type OidcProfileOwnerAuthorizer, type OidcProfileOwnerAuthorizerContext, type OidcProfileResolver, type OidcProfileResolverContext, OidcProvisioningError, type OidcProvisioningErrorCode, PermissionCollection, ResourceGrantCollection, RoleCollection, RolePermissionCollection, type RolePermissionPatternMatrix, type SeedRolePermissionsOptions, type SeedRolePermissionsResult, type SeedSystemRolesOptions, SessionCollection, TenantCollection, TenantHierarchyError, TenantIntegrationCollection, TenantPermissionOverrideCollection, type TenantPermissionOverrideResult, UserCollection, UsersCliAuthApproveLimitCollection, UsersCliAuthRequestCollection, UsersMagicLinkTokenCollection, } from './collections/index.js';
 export { type BackfillLegacyUserProfilesResult, backfillLegacyUserProfiles, LEGACY_USER_PROFILE_BACKFILL_NAME, LegacyUserProfileBackfillError, type LegacyUserProfileBackfillErrorCode, } from './migrations/backfillLegacyUserProfiles.js';
 export { type BackfillUserEmailKeysResult, backfillUserEmailKeys, type DuplicateUserEmailKey, UserEmailKeyBackfillError, type UserEmailKeyBackfillErrorCode, } from './migrations/backfillUserEmailKeys.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-import { $ as deriveOperationPermissionSlug, A as DEFAULT_ANCESTOR_READ_MAX_DEPTH, B as TenantPermissionOverride, C as OidcLoginService, Ct as UsersCliAuthRequestCollection, D as resolveOidcProviderConfig, Dt as generateSessionId, E as getUsersOidcConfig, Et as Session, F as UserCollection, G as applyTenantHierarchyUpdates, H as Tenant, J as recordTenantHierarchyChanges, K as assertTenantTableName, L as UserEmailKeyBackfillError, M as isAncestorReadableSlug, N as normalizeAncestorReadPolicy, Ot as UsersCliAuthRequest, P as OidcProvisioningError, Q as deriveOperationPermissionCollectionName, R as backfillUserEmailKeys, S as OidcLoginError, St as normalizeEmail, T as encodeOidcTransaction, Tt as DEFAULT_SESSION_TTL, U as MAX_TENANT_HIERARCHY_DEPTH, V as TenantCollection, W as TenantHierarchyError, X as RolePermissionCollection, Y as DEFAULT_ROLE_PERMISSION_PATTERNS, Z as PermissionCatalogService, _ as readMobileBearerToken, _t as Group, a as TerminalAuthRateLimitError, at as Role, b as PermissionResolver, bt as User, c as assertOperationPermission, ct as MembershipOverrideCollection, d as getCurrentSessionPermissionContext, dt as Membership, et as normalizeOperationPermissionAction, f as getRequestScopedDatabase, ft as GroupRoleCollection, g as MobileAuthService, gt as GroupCollection, h as MobileAuthError, ht as GroupMember, i as TerminalAuthError, it as RoleCollection, j as getConfiguredAncestorReadPolicy, k as ANCESTOR_READ_ACTION, l as checkOperationPermission, lt as MembershipOverride, m as withSessionPermissionContext, mt as GroupMemberCollection, n as DEFAULT_CLI_AUTH_REQUEST_TTL_SECONDS, nt as syncPermissionCatalog, o as TerminalAuthService, ot as PermissionCollection, p as withPrincipalPermissionContext, pt as GroupRole, q as planTenantHierarchy, r as DEFAULT_CLI_SESSION_TTL_SECONDS, rt as RolePermission, s as OperationPermissionError, st as Permission, t as DEFAULT_CLI_AUTH_POLL_INTERVAL_SECONDS, tt as registerPermissionDefinitions, u as hasOperationPermission, ut as MembershipCollection, v as validateMobileRedirectUri, vt as UsersCliAuthApproveLimitCollection, w as decodeOidcTransaction, wt as SessionCollection, x as withoutListBounds, xt as isValidEmail, y as SessionService, yt as UsersCliAuthApproveLimit, z as TenantPermissionOverrideCollection } from "./chunks/TerminalAuthService-COafLOPX.js";
+import { $ as deriveOperationPermissionSlug, A as DEFAULT_ANCESTOR_READ_MAX_DEPTH, B as TenantPermissionOverride, C as OidcLoginService, Ct as UsersCliAuthRequestCollection, D as resolveOidcProviderConfig, Dt as generateSessionId, E as getUsersOidcConfig, Et as Session, F as UserCollection, G as applyTenantHierarchyUpdates, H as Tenant, J as recordTenantHierarchyChanges, K as assertTenantTableName, L as UserEmailKeyBackfillError, M as isAncestorReadableSlug, N as normalizeAncestorReadPolicy, Ot as UsersCliAuthRequest, P as OidcProvisioningError, Q as deriveOperationPermissionCollectionName, R as backfillUserEmailKeys, S as OidcLoginError, St as normalizeEmail, T as encodeOidcTransaction, Tt as DEFAULT_SESSION_TTL, U as MAX_TENANT_HIERARCHY_DEPTH, V as TenantCollection, W as TenantHierarchyError, X as RolePermissionCollection, Y as DEFAULT_ROLE_PERMISSION_PATTERNS, Z as PermissionCatalogService, _ as readMobileBearerToken, _t as Group, a as TerminalAuthRateLimitError, at as Role, b as PermissionResolver, bt as User, c as assertOperationPermission, ct as MembershipOverrideCollection, d as getCurrentSessionPermissionContext, dt as Membership, et as normalizeOperationPermissionAction, f as getRequestScopedDatabase, ft as GroupRoleCollection, g as MobileAuthService, gt as GroupCollection, h as MobileAuthError, ht as GroupMember, i as TerminalAuthError, it as RoleCollection, j as getConfiguredAncestorReadPolicy, k as ANCESTOR_READ_ACTION, l as checkOperationPermission, lt as MembershipOverride, m as withSessionPermissionContext, mt as GroupMemberCollection, n as DEFAULT_CLI_AUTH_REQUEST_TTL_SECONDS, nt as syncPermissionCatalog, o as TerminalAuthService, ot as PermissionCollection, p as withPrincipalPermissionContext, pt as GroupRole, q as planTenantHierarchy, r as DEFAULT_CLI_SESSION_TTL_SECONDS, rt as RolePermission, s as OperationPermissionError, st as Permission, t as DEFAULT_CLI_AUTH_POLL_INTERVAL_SECONDS, tt as registerPermissionDefinitions, u as hasOperationPermission, ut as MembershipCollection, v as validateMobileRedirectUri, vt as UsersCliAuthApproveLimitCollection, w as decodeOidcTransaction, wt as SessionCollection, x as withoutListBounds, xt as isValidEmail, y as SessionService, yt as UsersCliAuthApproveLimit, z as TenantPermissionOverrideCollection } from "./chunks/TerminalAuthService-CLDmxYuC.js";
 import { a as MembershipStatus, c as TenantPermissionEffect, i as DEFAULT_TENANT_POLICY, l as TenantStatus, n as DEFAULT_ROLES, o as OverrideEffect, r as DEFAULT_ROLE_SLUGS, s as SessionStatus, t as AccessRequestStatus, u as UserStatus } from "./chunks/types-DFqeph0R.js";
 import { ObjectRegistry, SmrtCollection, SmrtObject, field, findManifestEntryByQualifiedName, foreignKey, isUniqueViolationError, registerRetentionTask, smrt, unregisterRetentionTask } from "@happyvertical/smrt-core";
 import { PROFILE_EMAIL_KEY_BACKFILL_NAME, Person, ProfileCollection, ProfileTypeCollection, normalizeIdentityEmail } from "@happyvertical/smrt-profiles";
@@ -1194,7 +1194,7 @@ var MagicLinkService = class MagicLinkService {
 	* The caller is responsible for emailing the token to the user.
 	*/
 	async generate(email) {
-		const { SignJWT } = await import("./chunks/TerminalAuthService-COafLOPX.js").then((n) => n.O);
+		const { SignJWT } = await import("./chunks/TerminalAuthService-CLDmxYuC.js").then((n) => n.O);
 		const key = await this.getSigningKey();
 		const nonce = crypto.randomUUID();
 		const normalizedEmail = normalizeEmail(email);
@@ -1223,7 +1223,7 @@ var MagicLinkService = class MagicLinkService {
 	* @throws {MagicLinkError} If the token is invalid, expired, or already used
 	*/
 	async verify(token) {
-		const { jwtVerify, errors } = await import("./chunks/TerminalAuthService-COafLOPX.js").then((n) => n.O);
+		const { jwtVerify, errors } = await import("./chunks/TerminalAuthService-CLDmxYuC.js").then((n) => n.O);
 		const key = await this.getSigningKey();
 		let payload;
 		try {

package/dist/manifest.json

@@ -2,7 +2,7 @@
   "version": "1.0.0",
   "timestamp": 0,
   "packageName": "@happyvertical/smrt-users",
-  "packageVersion": "0.51.31",
+  "packageVersion": "0.51.33",
   "objects": {
     "@happyvertical/smrt-users:AccessRequestCollection": {
       "name": "accessrequestcollection",

package/dist/migrations/backfillLegacyUserProfiles.d.ts

@@ -1,4 +1,4 @@
-import { getDatabase } from '@happyvertical/sql';
+import type { getDatabase } from '@happyvertical/sql';
 type DatabaseInterface = Awaited<ReturnType<typeof getDatabase>>;
 export declare const LEGACY_USER_PROFILE_BACKFILL_NAME = "@happyvertical/smrt-users:legacy-user-profiles:v1";
 export interface BackfillLegacyUserProfilesResult {

package/dist/migrations/backfillUserEmailKeys.d.ts

@@ -1,4 +1,4 @@
-import { getDatabase } from '@happyvertical/sql';
+import type { getDatabase } from '@happyvertical/sql';
 type DatabaseInterface = Awaited<ReturnType<typeof getDatabase>>;
 export declare const USER_EMAIL_KEY_BACKFILL_NAME = "@happyvertical/smrt-users:user-email-keys:v1";
 export interface DuplicateUserEmailKey {

package/dist/migrations/materializeTenantHierarchy.d.ts

@@ -1,5 +1,5 @@
-import { getDatabase } from '@happyvertical/sql';
-import { TenantHierarchyPlan, TenantHierarchyProblem } from '../models/tenant-hierarchy.js';
+import type { getDatabase } from '@happyvertical/sql';
+import { type TenantHierarchyPlan, type TenantHierarchyProblem } from '../models/tenant-hierarchy.js';
 type DatabaseInterface = Awaited<ReturnType<typeof getDatabase>>;
 /** Options for {@link materializeTenantHierarchy}. */
 export interface MaterializeTenantHierarchyOptions {

package/dist/models/AccessRequest.d.ts

@@ -1,3 +1,25 @@
+/**
+ * AccessRequest model — the "request access / join the waitlist" identity
+ * primitive.
+ *
+ * Captures a prospective user from a public form *before* they are a real
+ * {@link User}: an operator triages the record, then either declines it or
+ * approves and **graduates** it into a `User` (optionally attached to a
+ * tenant). This keeps the `User` table clean — unverified/spam signups live as
+ * requests, not users — while still giving operators a triage queue.
+ *
+ * The generated REST/MCP/CLI surface is intentionally CLOSED (`include: []`):
+ * every read and mutation must go through {@link AccessRequestService} so the
+ * public-safe creation path (email normalization + dedup), the lifecycle state
+ * machine, capability gating, and event emission can never be bypassed by a
+ * generated CRUD route. Creation is meant to be exposed *unauthenticated* by
+ * consuming apps via their own rate-limited endpoint calling
+ * `createAccessRequest`. The model is still registered (and its table created
+ * via the consumer's normal migrate flow) regardless of the empty generation
+ * config.
+ *
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
 import { AccessRequestStatus } from '../types/index.js';
 /**

package/dist/models/CliAuthApproveLimit.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Durable per-user failed-approval budget for terminal device codes.
+ *
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
 /** Private database arbiter shared by every terminal-auth process. */
 export declare class UsersCliAuthApproveLimit extends SmrtObject {

package/dist/models/CliAuthRequest.d.ts

@@ -1,3 +1,15 @@
+/**
+ * UsersCliAuthRequest model — device-code grant for terminal/CLI logins.
+ *
+ * Backs the "browser approves a terminal" flow: a CLI starts a request, the
+ * server returns a short user code, the user signs in on a browser and
+ * approves the code, then the CLI polls and gets back a session token bound
+ * to the approving user. Records are short-lived (TTL is enforced by
+ * `expiresAt`) and store only a hash of the device code so the raw device
+ * code is never recoverable from the database.
+ *
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
 /**
  * CLI auth request lifecycle states.

package/dist/models/Group.d.ts

@@ -1,4 +1,8 @@
-import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+/**
+ * Group model - team within a tenant
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
 /**
  * Constructor options for {@link Group}.
  */

package/dist/models/GroupMember.d.ts

@@ -1,4 +1,8 @@
-import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+/**
+ * GroupMember model - User belongs to Group (join table)
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
 /**
  * Constructor options for {@link GroupMember}.
  */

package/dist/models/GroupRole.d.ts

@@ -1,4 +1,8 @@
-import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+/**
+ * GroupRole model - Group has Role (join table)
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
 /**
  * Constructor options for {@link GroupRole}.
  */

package/dist/models/MagicLinkToken.d.ts

@@ -1,4 +1,12 @@
-import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+/**
+ * MagicLinkToken model - replay protection for magic link authentication
+ *
+ * Stores nonces embedded in magic link JWTs to prevent replay attacks.
+ * Each nonce can only be used once within its expiry window.
+ *
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
 /**
  * Default magic link token expiry: 10 minutes in seconds
  */

package/dist/models/Membership.d.ts

@@ -1,5 +1,9 @@
-import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
-import { Membership as MembershipContract } from '@happyvertical/smrt-types';
+/**
+ * Membership model - User belongs to Tenant with a Role
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
+import type { Membership as MembershipContract } from '@happyvertical/smrt-types';
 import { MembershipStatus } from '../types/index.js';
 /**
  * Constructor options for {@link Membership}.

package/dist/models/MembershipOverride.d.ts

@@ -1,4 +1,8 @@
-import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+/**
+ * MembershipOverride model - per-user permission grant/deny
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
 import { OverrideEffect } from '../types/index.js';
 /**
  * Constructor options for {@link MembershipOverride}.

package/dist/models/Permission.d.ts

@@ -1,4 +1,8 @@
-import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+/**
+ * Permission model - named capability in the system
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
 /**
  * Parsed permission slug components
  */

package/dist/models/ResourceGrant.d.ts

@@ -1,4 +1,5 @@
-import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+/** Resource-scoped authorization grants. @packageDocumentation */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
 export type ResourceGrantEffect = 'grant' | 'deny';
 export interface ResourceGrantOptions extends SmrtObjectOptions {
     tenantId?: string;

package/dist/models/Role.d.ts

@@ -1,5 +1,9 @@
-import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
-import { Role as RoleContract } from '@happyvertical/smrt-types';
+/**
+ * Role model - permission template
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
+import type { Role as RoleContract } from '@happyvertical/smrt-types';
 /**
  * Constructor options for {@link Role}.
  */

package/dist/models/RolePermission.d.ts

@@ -1,4 +1,8 @@
-import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+/**
+ * RolePermission model - Role has Permission (join table)
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
 /**
  * Constructor options for {@link RolePermission}.
  */

package/dist/models/Session.d.ts

@@ -1,4 +1,8 @@
-import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+/**
+ * Session model - Server-side session management for authenticated users
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
 import { SessionStatus } from '../types/index.js';
 /**
  * Constructor options for {@link Session}.

package/dist/models/Tenant.d.ts

@@ -1,5 +1,9 @@
-import { SmrtObject, SmrtObjectOptions, SmrtSaveOptions } from '@happyvertical/smrt-core';
-import { Tenant as TenantContract } from '@happyvertical/smrt-types';
+/**
+ * Tenant model - organizational boundary for multi-tenancy
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions, type SmrtSaveOptions } from '@happyvertical/smrt-core';
+import type { Tenant as TenantContract } from '@happyvertical/smrt-types';
 import { TenantStatus } from '../types/index.js';
 /**
  * Constructor options for {@link Tenant}.

package/dist/models/TenantIntegration.d.ts

@@ -1,4 +1,13 @@
-import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+/**
+ * TenantIntegration model - per-tenant external integration provisioning state.
+ *
+ * One row per (tenantId, provider) tuple. Stores provider identifiers and
+ * health/provisioning metadata only; callers must keep secrets in a dedicated
+ * secret store such as @happyvertical/smrt-secrets.
+ *
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
 /**
  * Built-in provider names. The string type is intentionally open so apps can
  * add providers without a model migration.

package/dist/models/TenantPermissionOverride.d.ts

@@ -1,4 +1,8 @@
-import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+/**
+ * TenantPermissionOverride model - tenant-level permission grant/deny/inherit
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
 import { TenantPermissionEffect } from '../types/index.js';
 /**
  * Constructor options for {@link TenantPermissionOverride}.

package/dist/models/User.d.ts

@@ -1,5 +1,9 @@
-import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
-import { User as UserContract } from '@happyvertical/smrt-types';
+/**
+ * User model - authenticated identity linked to a Profile
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
+import type { User as UserContract } from '@happyvertical/smrt-types';
 import { UserStatus } from '../types/index.js';
 /**
  * Constructor options for {@link User}.

package/dist/models/tenant-hierarchy.d.ts

@@ -1,3 +1,26 @@
+/**
+ * Framework-maintained tenant hierarchy materialization (smrt#3036).
+ *
+ * `Tenant.hierarchyPath` / `hierarchyLevel` are DERIVED from the
+ * `parentTenantId` chain. They are an authorization source — the permission
+ * resolver walks them for `inheritsToDescendants` and for the declared
+ * ancestor-read policy — so the framework, not the consumer, keeps them
+ * current:
+ *
+ * - {@link Tenant.save} recomputes them from the real parent chain on every
+ *   save of any Tenant (including STI subclasses and rows created without the
+ *   collection helpers) and re-materializes descendants when they change.
+ * - {@link materializeTenantHierarchy} (exposed as the
+ *   `smrt db:materialize-tenant-hierarchy` CLI command) backfills rows written
+ *   before this was framework-maintained.
+ *
+ * Everything here reads and writes raw rows on the tenants table. That is
+ * deliberate: descendants may be STI subclasses, and re-saving them through a
+ * base-class instance could clobber subclass columns, while only the two
+ * derived columns ever change.
+ *
+ * @packageDocumentation
+ */
 import { bumpChangeFeed } from '@happyvertical/smrt-core';
 /**
  * Maximum allowed depth for tenant hierarchy.