@rovela-ai/sdk 0.4.1 → 0.4.2

package/dist/admin/server/user-management.d.ts

@@ -0,0 +1,221 @@
+/**
+ * @rovela/sdk/admin/server/user-management
+ *
+ * User lifecycle management for store admins — list, deactivate, reactivate,
+ * and hard-delete operations, with all invariants enforced at the service
+ * layer so every future caller inherits them automatically.
+ *
+ * # Invariants (enforced in every mutation)
+ *
+ *   1. Self-protection: actor cannot act on themselves via these helpers.
+ *      Self-service flows (password change, profile update) go through
+ *      dedicated `/api/admin/me/*` endpoints (Phase 4).
+ *
+ *   2. Last-owner protection: there must ALWAYS be at least one admin with
+ *      role='owner' AND status='active'. Deactivating, demoting, or deleting
+ *      the last active owner is rejected. This is enforced via an atomic
+ *      conditional UPDATE (or a pre-check for hard delete), not a
+ *      check-then-act pattern — no TOCTOU race window.
+ *
+ *   3. Lateral-escalation protection: administrators can only touch managers
+ *      and users. They cannot modify owners or other administrators.
+ *      Enforced via `canManageUser(actor, target)` from `permissions.ts`.
+ *
+ *   4. Hard delete requires prior deactivation: you cannot DELETE an admin
+ *      whose status is 'active' or 'invited'. Must call `deactivateAdmin`
+ *      first. This creates a two-step safety rail for irreversible actions.
+ *
+ *   5. Audit trail on deactivate: `deactivated_at` and `deactivated_by` are
+ *      populated from the service layer. Reactivate clears them.
+ *
+ *   6. Reactivate only applies to 'deactivated' admins, not 'invited'.
+ *      Invited admins must accept their invite (Phase 3) to become active.
+ *
+ * # Session cache invalidation
+ *
+ * Every mutation ends with `invalidateAdminSession(targetId)` so the 30-second
+ * per-admin status cache in `requireAdmin()` sees the new state on the very
+ * next request. Without this call, a deactivated admin could continue making
+ * authenticated requests for up to 30 seconds.
+ *
+ * # This module never throws on invariant failures — it returns a typed
+ * discriminated union `{ ok: true }` or `{ ok: false, error: {...} }`.
+ * Unexpected runtime errors (DB connectivity, etc.) still throw and bubble
+ * up to the API route's try/catch.
+ */
+import type { AdminRole } from '../../core/types';
+import type { StoreAdmin } from '../../core/db/schema';
+export interface AdminListOptions {
+    /** Case-insensitive substring match against name OR email. */
+    search?: string;
+    /** Filter by status. 'all' (default) returns every admin regardless of status. */
+    status?: 'all' | 'active' | 'invited' | 'deactivated';
+    /** Filter by role. 'all' (default) returns every admin regardless of role. */
+    role?: 'all' | AdminRole;
+    /** Max rows to return. Clamped to 1..100 at the API layer. */
+    limit?: number;
+    /** Offset for pagination (0-indexed). */
+    offset?: number;
+}
+export interface UserManagementError {
+    code: 'NOT_FOUND' | 'FORBIDDEN' | 'SELF_ACTION_FORBIDDEN' | 'LAST_OWNER_PROTECTED' | 'MUST_DEACTIVATE_FIRST' | 'INVALID_STATE' | 'VALIDATION_ERROR' | 'EMAIL_ALREADY_EXISTS' | 'EMAIL_ALREADY_INVITED' | 'EMAIL_DEACTIVATED_EXISTS';
+    message: string;
+}
+export type UserManagementResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: UserManagementError;
+};
+export interface Actor {
+    id: string;
+    role: AdminRole;
+}
+/**
+ * List admins with filters and pagination.
+ *
+ * Returns the raw `StoreAdmin` rows — the caller is responsible for stripping
+ * sensitive fields (`passwordHash`) before serializing to JSON. The API
+ * handler does this mapping.
+ */
+export declare function listAdmins(opts?: AdminListOptions): Promise<{
+    admins: StoreAdmin[];
+    total: number;
+}>;
+/**
+ * Count admins with role='owner' and status='active'.
+ *
+ * The single source of truth for the last-owner invariant. Always queried
+ * fresh — it's a one-row COUNT, trivially fast, and caching would introduce
+ * staleness risk for a safety-critical check.
+ */
+export declare function countActiveOwners(): Promise<number>;
+/**
+ * Soft-delete an admin: set status='deactivated' and stamp audit fields.
+ *
+ * Rejects on any invariant violation. Never throws on business errors;
+ * returns a typed result the caller can branch on.
+ *
+ * Uses an atomic conditional UPDATE to enforce the last-owner invariant —
+ * no check-then-act race window. If another request deactivates the second-
+ * to-last owner between our check and our update, our UPDATE's WHERE clause
+ * will match zero rows and we return LAST_OWNER_PROTECTED.
+ */
+export declare function deactivateAdmin(actor: Actor, targetId: string): Promise<UserManagementResult>;
+/**
+ * Reactivate a previously-deactivated admin: set status='active', clear
+ * audit fields. Does NOT apply to 'invited' admins — they must accept
+ * their invite (Phase 3) to become active.
+ */
+export declare function reactivateAdmin(actor: Actor, targetId: string): Promise<UserManagementResult>;
+/**
+ * Permanently delete an admin row. Cascades to `admin_password_reset_tokens`
+ * and `admin_invite_tokens` via the `ON DELETE CASCADE` foreign keys defined
+ * in the Phase 0 schema.
+ *
+ * Requires the target to already be 'deactivated' — this is a two-step
+ * irreversible action. The API route additionally gates on `users.delete`
+ * permission (owner-only), but we re-check here for defense-in-depth.
+ *
+ * Dangling `deactivated_by` / `created_by` references on other admin rows
+ * are intentionally left as dangling UUIDs. The UI renders them as
+ * "Unknown user". Phase 4 may revisit.
+ */
+export declare function hardDeleteAdmin(actor: Actor, targetId: string): Promise<UserManagementResult>;
+/**
+ * Map a `UserManagementError.code` to the HTTP status the API handler
+ * should respond with. Exported so both the API handlers and any future
+ * caller use the same mapping.
+ */
+export declare function statusCodeFor(code: UserManagementError['code']): number;
+export interface InviteAdminRequest {
+    email: string;
+    name: string;
+    role: AdminRole;
+}
+export interface InviteAdminSuccess {
+    ok: true;
+    adminId: string;
+    token: string;
+    inviteUrl: string;
+}
+export type InviteAdminResult = InviteAdminSuccess | {
+    ok: false;
+    error: UserManagementError;
+};
+/**
+ * Invite a new admin to manage the store.
+ *
+ * Creates a `store_admins` row in `invited` status with no password,
+ * issues an invite token (72h expiry), and sends the invite email. The
+ * caller receives both the token AND the fully-qualified invite URL — so
+ * if email delivery fails, the UI can show a "copy link manually"
+ * fallback instead of silently losing the invite.
+ *
+ * # Invariants (in order)
+ *
+ *   1. `canManageUser(actor, {role})` — actor can grant the requested role.
+ *      Administrators cannot invite owners or other administrators.
+ *   2. Valid email format + name length ≥ 2.
+ *   3. Email uniqueness — rejects with a distinct error code depending on
+ *      the existing row's status (active / invited / deactivated) so the
+ *      UI can show actionable messages.
+ *   4. Legal role: must be one of 'owner' | 'administrator' | 'manager' | 'user'.
+ *
+ * Email send failures are logged but NOT propagated — the invite row +
+ * token are already persisted, the caller gets the URL, and the UI
+ * handles fallback display.
+ */
+export declare function inviteAdmin(actor: Actor, request: InviteAdminRequest): Promise<InviteAdminResult>;
+export interface ResendInviteSuccess {
+    ok: true;
+    token: string;
+    inviteUrl: string;
+}
+export type ResendInviteResult = ResendInviteSuccess | {
+    ok: false;
+    error: UserManagementError;
+};
+/**
+ * Resend an invite to an admin who is still in `invited` status.
+ *
+ * Generates a fresh token (invalidating any previous ones) and resends
+ * the email. Preserves the single-active-token policy — older tokens
+ * are deleted before the new one is created.
+ */
+export declare function resendAdminInvite(actor: Actor, targetId: string): Promise<ResendInviteResult>;
+/**
+ * Cancel a pending invite. Hard-deletes the `store_admins` row — which
+ * cascades via FK to delete all `admin_invite_tokens` rows for that
+ * admin. Only valid for `invited` status (not `active` / `deactivated`).
+ *
+ * Uses `users.write` permission (administrators + owners), unlike the
+ * DELETE endpoint which is owner-only. Canceling an invite for a manager
+ * or user is a normal administrator action, not a destructive one.
+ */
+export declare function cancelAdminInvite(actor: Actor, targetId: string): Promise<UserManagementResult>;
+/**
+ * Change an admin's role.
+ *
+ * Invariants (in strict order):
+ *
+ *   1. Target exists (→ NOT_FOUND).
+ *   2. Self-protection — actor cannot change their own role (→
+ *      SELF_ACTION_FORBIDDEN). A solo owner needing to demote themselves
+ *      must either invite another owner first, or use a future Phase 4
+ *      emergency-reset flow.
+ *   3. canManageUser at CURRENT role — actor must be allowed to manage
+ *      the target at their current role (administrator cannot touch
+ *      owners or other administrators).
+ *   4. canManageUser at NEW role — actor must be allowed to grant the
+ *      new role (administrator cannot promote to administrator/owner).
+ *   5. No-op fast path — if newRole === current role, return success
+ *      without touching the DB.
+ *   6. Last-owner protection — if target is currently 'owner' and the
+ *      new role is not 'owner', require `countActiveOwners() > 1`.
+ *      Enforced atomically via a conditional UPDATE so there's no
+ *      check-then-act race window.
+ *   7. Update; invalidate session cache.
+ */
+export declare function changeAdminRole(actor: Actor, targetId: string, newRole: AdminRole): Promise<UserManagementResult>;
+//# sourceMappingURL=user-management.d.ts.map

package/dist/admin/server/user-management.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-management.d.ts","sourceRoot":"","sources":["../../../src/admin/server/user-management.ts"],"names":[],"mappings":"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"}