@rovela-ai/sdk 0.4.0 → 0.4.1

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

@@ -1,221 +0,0 @@
-/**
- * @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

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