@happyvertical/smrt-types 0.51.32 → 0.51.34

package/dist/signals.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Universal Signaling System Types
+ *
+ * This module defines the core types for the SMRT signaling system,
+ * which provides automatic method tracking and event distribution
+ * for logging, metrics, pub/sub, and other observability needs.
+ */
+/**
+ * Lifecycle stage of a signal emitted during SMRT method execution.
+ *
+ * - `'start'` — emitted when a tracked method begins executing
+ * - `'step'`  — emitted manually within a method for progress tracking
+ * - `'end'`   — emitted when a method completes successfully
+ * - `'error'` — emitted when a method throws an unhandled exception
+ *
+ * @example
+ * ```typescript
+ * adapter.handle = async (signal: Signal) => {
+ *   if (signal.type === 'error') {
+ *     logger.error(`${signal.className}.${signal.method} failed`, signal.error);
+ *   }
+ * };
+ * ```
+ *
+ * @see {@link Signal} for the full signal payload shape
+ * @see {@link SignalAdapter} for consuming signals
+ */
+export type SignalType = 'start' | 'step' | 'end' | 'error';
+/**
+ * Signal emitted during SMRT method execution.
+ *
+ * Signals provide automatic observability into method execution,
+ * enabling logging, metrics, pub/sub updates, and other integrations
+ * without requiring manual instrumentation.
+ *
+ * @example
+ * ```typescript
+ * // Logging adapter
+ * const loggingAdapter: SignalAdapter = {
+ *   async handle(signal: Signal) {
+ *     const label = `${signal.className}.${signal.method} [${signal.id}]`;
+ *     if (signal.type === 'start')  console.log(`→ ${label}`);
+ *     if (signal.type === 'end')    console.log(`✓ ${label} (${signal.duration}ms)`);
+ *     if (signal.type === 'error')  console.error(`✗ ${label}`, signal.error);
+ *   },
+ * };
+ * ```
+ *
+ * @see {@link SignalType} for the lifecycle stage values
+ * @see {@link SignalAdapter} for implementing a consumer
+ */
+export interface Signal {
+    /**
+     * Unique identifier for this specific execution
+     * Generated once per method invocation
+     */
+    id: string;
+    /**
+     * ID of the SMRT object instance
+     */
+    objectId: string;
+    /**
+     * Name of the SMRT class
+     */
+    className: string;
+    /**
+     * Name of the method being executed
+     */
+    method: string;
+    /**
+     * Signal type indicating lifecycle stage:
+     * - 'start': Method execution started
+     * - 'step': Manual step within method (optional)
+     * - 'end': Method execution completed successfully
+     * - 'error': Method execution failed
+     */
+    type: SignalType;
+    /**
+     * Optional step label for manual progress tracking
+     * Developers can emit custom steps within methods using bus.emit()
+     */
+    step?: string;
+    /**
+     * Sanitized method arguments (sensitive data removed)
+     * Objects with @sensitive JSDoc tags are excluded
+     */
+    args?: unknown[];
+    /**
+     * Method result (only present on 'end' signals)
+     */
+    result?: unknown;
+    /**
+     * Error that was thrown (only present on 'error' signals)
+     */
+    error?: Error;
+    /**
+     * Method execution duration in milliseconds
+     * Only present on 'end' and 'error' signals
+     */
+    duration?: number;
+    /**
+     * Timestamp when signal was emitted
+     */
+    timestamp: Date;
+    /**
+     * Optional additional context
+     * Can include tracing IDs, user context, request metadata, etc.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Adapter interface for consuming signals from the SMRT signaling system.
+ *
+ * Adapters process signals for specific purposes:
+ * - **Logging**: write to console, file, or a logging service
+ * - **Metrics**: track execution counts, durations, and error rates
+ * - **Pub/Sub**: broadcast real-time updates to connected clients
+ * - **Tracing**: forward spans to a distributed tracing system (e.g., OpenTelemetry)
+ *
+ * Adapters are fire-and-forget — errors thrown inside `handle()` are caught
+ * by the SignalBus and do not interrupt the main execution flow.
+ *
+ * @example
+ * ```typescript
+ * class MetricsAdapter implements SignalAdapter {
+ *   async handle(signal: Signal): Promise<void> {
+ *     if (signal.type === 'end') {
+ *       metrics.histogram('smrt.method.duration', signal.duration ?? 0, {
+ *         class: signal.className,
+ *         method: signal.method,
+ *       });
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link Signal} for the payload each adapter receives
+ * @see {@link SignalType} for the lifecycle stages
+ */
+export interface SignalAdapter {
+    /**
+     * Handle a signal event
+     *
+     * @param signal - The signal to process
+     * @returns Promise that resolves when signal is handled
+     *
+     * @remarks
+     * This method should not throw - errors are caught by the SignalBus.
+     * Implementations should handle their own error logging/recovery.
+     */
+    handle(signal: Signal): Promise<void>;
+}
+//# sourceMappingURL=signals.d.ts.map

package/dist/signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.d.ts","sourceRoot":"","sources":["../src/signals.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,MAAM;IACrB;;;OAGG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,IAAI,EAAE,UAAU,CAAC;IAEjB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IAEjB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;IAEd;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,SAAS,EAAE,IAAI,CAAC;IAEhB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;OASG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC"}

package/dist/user.d.ts

@@ -0,0 +1,189 @@
+/**
+ * User-related type definitions
+ *
+ * These enums and types are exported from smrt-types to allow
+ * browser-safe packages (like smrt-svelte) to import them without
+ * pulling in server-side dependencies from smrt-users.
+ */
+/**
+ * Lifecycle status of a user account.
+ *
+ * @example
+ * ```typescript
+ * if (user.status === UserStatus.SUSPENDED) {
+ *   throw new ForbiddenError('Account is suspended');
+ * }
+ * ```
+ *
+ * @see {@link MembershipStatus} for a user's status within a specific tenant
+ * @see {@link SessionStatus} for the status of an active session
+ */
+export declare enum UserStatus {
+    /** Active user account */
+    ACTIVE = "active",
+    /** Inactive user account */
+    INACTIVE = "inactive",
+    /** Suspended user account */
+    SUSPENDED = "suspended",
+    /** Pending email verification */
+    PENDING = "pending"
+}
+/**
+ * Lifecycle status of a tenant (organization) within the platform.
+ *
+ * @example
+ * ```typescript
+ * if (tenant.status === TenantStatus.ARCHIVED) {
+ *   return; // skip soft-deleted tenants
+ * }
+ * ```
+ *
+ * @see {@link MembershipStatus} for a user's membership status within a tenant
+ * @see {@link TenantPermissionEffect} for permission inheritance across tenant hierarchies
+ */
+export declare enum TenantStatus {
+    /** Active tenant */
+    ACTIVE = "active",
+    /** Inactive tenant */
+    INACTIVE = "inactive",
+    /** Suspended tenant */
+    SUSPENDED = "suspended",
+    /** Archived tenant (soft-deleted) */
+    ARCHIVED = "archived"
+}
+/**
+ * Status of a user's membership within a specific tenant.
+ *
+ * A user may hold memberships in multiple tenants simultaneously, each with an
+ * independent `MembershipStatus`.
+ *
+ * @example
+ * ```typescript
+ * const active = memberships.filter(m => m.status === MembershipStatus.ACTIVE);
+ * ```
+ *
+ * @see {@link UserStatus} for the global account-level status
+ * @see {@link TenantStatus} for the status of the tenant itself
+ */
+export declare enum MembershipStatus {
+    /** Active membership */
+    ACTIVE = "active",
+    /** Inactive membership */
+    INACTIVE = "inactive",
+    /** Pending invitation acceptance */
+    PENDING = "pending"
+}
+/**
+ * Lifecycle status of an {@link AccessRequest} — the "request access / join the
+ * waitlist" identity primitive that captures a prospective user from a public
+ * form before they become a real `User`.
+ *
+ * Operators triage `REQUESTED` records, then either decline them or approve and
+ * **graduate** them into a `User` (optionally attached to a tenant).
+ *
+ * State machine:
+ * ```
+ * REQUESTED ──approve──> APPROVED ──graduate──> GRADUATED
+ *     │                      │
+ *     ├──decline──> DECLINED ┘ (decline also valid from APPROVED)
+ *     └──cancel───> CANCELED
+ * ```
+ *
+ * @example
+ * ```typescript
+ * if (request.status === AccessRequestStatus.APPROVED) {
+ *   await service.graduateAccessRequest(request.id, { by: operatorId });
+ * }
+ * ```
+ *
+ * @see {@link UserStatus} for the account-level status set when a request graduates
+ */
+export declare enum AccessRequestStatus {
+    /** Open request awaiting operator triage (the default on creation) */
+    REQUESTED = "requested",
+    /** Operator approved the request; ready to graduate into a User */
+    APPROVED = "approved",
+    /** Operator declined the request */
+    DECLINED = "declined",
+    /** Request was graduated into a real User (terminal) */
+    GRADUATED = "graduated",
+    /** Request was canceled before a decision (terminal) */
+    CANCELED = "canceled"
+}
+/**
+ * Status of an authenticated session.
+ *
+ * Sessions transition from `ACTIVE` to either `EXPIRED` (time-based) or
+ * `REVOKED` (explicit action by the user or an administrator).
+ *
+ * @example
+ * ```typescript
+ * if (session.status !== SessionStatus.ACTIVE) {
+ *   redirect(302, '/login');
+ * }
+ * ```
+ *
+ * @see {@link UserStatus} for the account-level status checked before session creation
+ */
+export declare enum SessionStatus {
+    /** Active session */
+    ACTIVE = "active",
+    /** Expired session (past expiresAt) */
+    EXPIRED = "expired",
+    /** Revoked by user or admin */
+    REVOKED = "revoked"
+}
+/**
+ * Effect applied by a user-level permission override.
+ *
+ * Overrides target a specific user + permission combination and always win
+ * over role-based grants. `DENY` overrides are checked before `GRANT` in
+ * the 4-level permission cascade.
+ *
+ * @example
+ * ```typescript
+ * await override.create({
+ *   userId,
+ *   permission: 'billing.view',
+ *   effect: OverrideEffect.DENY,
+ * });
+ * ```
+ *
+ * @see {@link TenantPermissionEffect} for the tenant-level equivalent that supports inheritance
+ */
+export declare enum OverrideEffect {
+    /** Grant the permission */
+    GRANT = "grant",
+    /** Deny the permission */
+    DENY = "deny"
+}
+/**
+ * Effect of a tenant-level permission setting in a hierarchical tenant tree.
+ *
+ * Unlike `OverrideEffect`, tenant-level effects support `INHERIT` — the default
+ * behaviour where a child tenant walks up to its parent to resolve the permission.
+ * `DENY` blocks inheritance, preventing child tenants from acquiring the permission
+ * even if a grandparent grants it.
+ *
+ * @example
+ * ```typescript
+ * // Sub-tenant explicitly blocks billing access regardless of parent settings
+ * await tenantPermission.create({
+ *   tenantId: subTenantId,
+ *   permission: 'billing.manage',
+ *   effect: TenantPermissionEffect.DENY,
+ * });
+ * ```
+ *
+ * @see {@link OverrideEffect} for user-level overrides (no inheritance step)
+ * @see {@link TenantStatus} for the tenant lifecycle status
+ */
+export declare enum TenantPermissionEffect {
+    /** Inherit from parent tenant (default behavior) */
+    INHERIT = "inherit",
+    /** Explicitly grant at this tenant level */
+    GRANT = "grant",
+    /** Explicitly deny at this tenant level (blocks inheritance) */
+    DENY = "deny"
+}
+//# sourceMappingURL=user.d.ts.map

package/dist/user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../src/user.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;;;;;;;GAYG;AACH,oBAAY,UAAU;IACpB,0BAA0B;IAC1B,MAAM,WAAW;IACjB,4BAA4B;IAC5B,QAAQ,aAAa;IACrB,6BAA6B;IAC7B,SAAS,cAAc;IACvB,iCAAiC;IACjC,OAAO,YAAY;CACpB;AAID;;;;;;;;;;;;GAYG;AACH,oBAAY,YAAY;IACtB,oBAAoB;IACpB,MAAM,WAAW;IACjB,sBAAsB;IACtB,QAAQ,aAAa;IACrB,uBAAuB;IACvB,SAAS,cAAc;IACvB,qCAAqC;IACrC,QAAQ,aAAa;CACtB;AAID;;;;;;;;;;;;;GAaG;AACH,oBAAY,gBAAgB;IAC1B,wBAAwB;IACxB,MAAM,WAAW;IACjB,0BAA0B;IAC1B,QAAQ,aAAa;IACrB,oCAAoC;IACpC,OAAO,YAAY;CACpB;AAID;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,oBAAY,mBAAmB;IAC7B,sEAAsE;IACtE,SAAS,cAAc;IACvB,mEAAmE;IACnE,QAAQ,aAAa;IACrB,oCAAoC;IACpC,QAAQ,aAAa;IACrB,wDAAwD;IACxD,SAAS,cAAc;IACvB,wDAAwD;IACxD,QAAQ,aAAa;CACtB;AAID;;;;;;;;;;;;;;GAcG;AACH,oBAAY,aAAa;IACvB,qBAAqB;IACrB,MAAM,WAAW;IACjB,uCAAuC;IACvC,OAAO,YAAY;IACnB,+BAA+B;IAC/B,OAAO,YAAY;CACpB;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,oBAAY,cAAc;IACxB,2BAA2B;IAC3B,KAAK,UAAU;IACf,0BAA0B;IAC1B,IAAI,SAAS;CACd;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,oBAAY,sBAAsB;IAChC,oDAAoD;IACpD,OAAO,YAAY;IACnB,4CAA4C;IAC5C,KAAK,UAAU;IACf,gEAAgE;IAChE,IAAI,SAAS;CACd"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-types",
-  "version": "0.51.32",
+  "version": "0.51.34",
   "description": "Shared type definitions for the HAVE SDK",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,7 +13,7 @@
   },
   "devDependencies": {
     "@types/node": "24.13.6",
-    "typescript": "5.9.3",
+    "typescript": "6.0.3",
     "vite": "8.1.4",
     "vitest": "4.1.10"
   },