@stackcraftmx/calcita 0.0.0-stage → 0.23.0

package/dist/types/account/accountConnector.d.ts

@@ -0,0 +1,263 @@
+export type AccountUser = {
+    id: string;
+    name: string;
+    email: string;
+    /**
+     * el renglón bajo el nombre (puesto · sucursal)
+     */
+    subtitle?: string;
+    phone?: string;
+    avatarUrl?: string;
+};
+export type AccountSession = {
+    user: AccountUser;
+    roles?: string[];
+    abilities?: string[];
+    /**
+     * sus perfiles o etiquetas, ya traducidos (salen como chips en Mi perfil)
+     */
+    labels?: string[];
+};
+export type AccountSecurity = {
+    isEnabled: boolean;
+    enabledAt?: string | null;
+    passkeys: Array<{
+        id: string;
+        name: string;
+        createdAt: string;
+        lastUsedAt?: string | null;
+    }>;
+    totp: {
+        isEnabled: boolean;
+        enabledAt?: string | null;
+    };
+    recoveryCodesRemaining: number;
+};
+export type AccountSecurityChange = {
+    security: AccountSecurity;
+    recoveryCodes?: string[];
+};
+export type AccountDeviceSession = {
+    id: string;
+    browser?: string | null;
+    platform?: string | null;
+    isMobile?: boolean;
+    /**
+     * instante ISO
+     */
+    startedAt: string;
+    /**
+     * a medias (187.190.x.x), nunca la IP completa
+     */
+    network?: string | null;
+    isCurrent?: boolean;
+};
+export type AccountEvent = {
+    id: string;
+    /**
+     * uno de ACCOUNT_EVENT_KIND
+     */
+    kind: string;
+    /**
+     * instante ISO
+     */
+    occurredAt: string;
+    device?: string | null;
+    network?: string | null;
+};
+export type AccountConnector = {
+    /**
+     * quién está dentro; null si nadie
+     */
+    loadSession: () => Promise<AccountSession | null>;
+    /**
+     *     con verificación en dos pasos regresa los métodos del segundo paso (SECOND_STEP_METHOD); sin ella, secondStep null
+     *     y ya está dentro
+     */
+    signIn: (credentials: {
+        email: string;
+        password: string;
+        remember: boolean;
+    }) => Promise<{
+        secondStep: {
+            methods: string[];
+        } | null;
+    }>;
+    /**
+     * el código de la app (totp) o uno
+     * de recuperación (recoveryCode)
+     */
+    signInSecondStep: (input: {
+        method: string;
+        code: string;
+    }) => Promise<void>;
+    /**
+     * las opciones de WebAuthn para firmar (JSON del servidor)
+     */
+    secondStepPasskeyOptions: () => Promise<object>;
+    /**
+     * la firma del navegador (JSON de WebAuthn)
+     */
+    signInWithPasskey: (credential: any) => Promise<void>;
+    signOut: () => Promise<void>;
+    /**
+     * contesta igual exista o no el correo
+     */
+    requestPasswordReset: (input: {
+        email: string;
+    }) => Promise<void>;
+    /**
+     * desde el enlace del correo
+     */
+    resetPassword: (input: {
+        token: string;
+        newPassword: string;
+    }) => Promise<void>;
+    updateProfile: (input: {
+        name: string;
+        phone: string;
+    }) => Promise<{
+        message?: string;
+    } | void>;
+    changePassword: (input: {
+        currentPassword?: string;
+        newPassword: string;
+    }) => Promise<void>;
+    loadSecurity: () => Promise<AccountSecurity>;
+    /**
+     * una clave nueva (todavía sin activar)
+     */
+    startTotp: () => Promise<{
+        secret: string;
+        qrImageUrl?: string | null;
+    }>;
+    confirmTotp: (code: string) => Promise<AccountSecurityChange>;
+    disableTotp: (password: string) => Promise<AccountSecurityChange>;
+    /**
+     * las opciones de WebAuthn para crear una llave
+     */
+    passkeyRegistrationOptions: () => Promise<object>;
+    savePasskey: (input: {
+        name: string;
+        credential: any;
+    }) => Promise<AccountSecurityChange>;
+    removePasskey: (input: {
+        passkeyId: string;
+        password: string;
+    }) => Promise<AccountSecurityChange>;
+    regenerateRecoveryCodes: (password: string) => Promise<AccountSecurityChange>;
+    listSessions: () => Promise<AccountDeviceSession[]>;
+    /**
+     * cuántas cerró
+     */
+    closeOtherSessions: () => Promise<number>;
+    /**
+     * de lo más nuevo a lo más viejo
+     */
+    listActivity: () => Promise<AccountEvent[]>;
+    /**
+     * SOLO en la demostración: el código que enseñaría la app ahorita
+     * (con él sale el botón «Usar el código de ejemplo»)
+     */
+    demoTotpCode?: () => Promise<string | null>;
+};
+/**
+ * Quien está dentro, como lo pintan la barra y Mi perfil.
+ *
+ * @typedef {object} AccountUser
+ * @property {string} id
+ * @property {string} name
+ * @property {string} email
+ * @property {string} [subtitle] el renglón bajo el nombre (puesto · sucursal)
+ * @property {string} [phone]
+ * @property {string} [avatarUrl]
+ */
+/**
+ * La sesión: quién está dentro y sus permisos (los lee createAccessChecker).
+ *
+ * @typedef {object} AccountSession
+ * @property {AccountUser} user
+ * @property {string[]} [roles]
+ * @property {string[]} [abilities]
+ * @property {string[]} [labels] sus perfiles o etiquetas, ya traducidos (salen como chips en Mi perfil)
+ */
+/**
+ * El estado de la verificación en dos pasos (el que pinta TwoStepVerificationCard).
+ *
+ * @typedef {object} AccountSecurity
+ * @property {boolean} isEnabled
+ * @property {string|null} [enabledAt]
+ * @property {Array<{id: string, name: string, createdAt: string, lastUsedAt?: string|null}>} passkeys
+ * @property {{isEnabled: boolean, enabledAt?: string|null}} totp
+ * @property {number} recoveryCodesRemaining
+ */
+/**
+ * Lo que regresa un cambio de seguridad: el estado nuevo y, si se generaron, los códigos de recuperación (se enseñan una
+ * sola vez).
+ *
+ * @typedef {object} AccountSecurityChange
+ * @property {AccountSecurity} security
+ * @property {string[]} [recoveryCodes]
+ */
+/**
+ * Un equipo donde la cuenta está abierta.
+ *
+ * @typedef {object} AccountDeviceSession
+ * @property {string} id
+ * @property {string|null} [browser]
+ * @property {string|null} [platform]
+ * @property {boolean} [isMobile]
+ * @property {string} startedAt instante ISO
+ * @property {string|null} [network] a medias (187.190.x.x), nunca la IP completa
+ * @property {boolean} [isCurrent]
+ */
+/**
+ * Un renglón de la bitácora de la cuenta.
+ *
+ * @typedef {object} AccountEvent
+ * @property {string} id
+ * @property {string} kind uno de ACCOUNT_EVENT_KIND
+ * @property {string} occurredAt instante ISO
+ * @property {string|null} [device]
+ * @property {string|null} [network]
+ */
+/**
+ * El conector completo.
+ *
+ * @typedef {object} AccountConnector
+ * @property {() => Promise<AccountSession|null>} loadSession quién está dentro; null si nadie
+ * @property {(credentials: {email: string, password: string, remember: boolean}) => Promise<{secondStep: {methods: string[]}|null}>} signIn
+ *     con verificación en dos pasos regresa los métodos del segundo paso (SECOND_STEP_METHOD); sin ella, secondStep null
+ *     y ya está dentro
+ * @property {(input: {method: string, code: string}) => Promise<void>} signInSecondStep el código de la app (totp) o uno
+ *     de recuperación (recoveryCode)
+ * @property {() => Promise<object>} secondStepPasskeyOptions las opciones de WebAuthn para firmar (JSON del servidor)
+ * @property {(credential: any) => Promise<void>} signInWithPasskey la firma del navegador (JSON de WebAuthn)
+ * @property {() => Promise<void>} signOut
+ * @property {(input: {email: string}) => Promise<void>} requestPasswordReset contesta igual exista o no el correo
+ * @property {(input: {token: string, newPassword: string}) => Promise<void>} resetPassword desde el enlace del correo
+ * @property {(input: {name: string, phone: string}) => Promise<{message?: string}|void>} updateProfile
+ * @property {(input: {currentPassword?: string, newPassword: string}) => Promise<void>} changePassword
+ * @property {() => Promise<AccountSecurity>} loadSecurity
+ * @property {() => Promise<{secret: string, qrImageUrl?: string|null}>} startTotp una clave nueva (todavía sin activar)
+ * @property {(code: string) => Promise<AccountSecurityChange>} confirmTotp
+ * @property {(password: string) => Promise<AccountSecurityChange>} disableTotp
+ * @property {() => Promise<object>} passkeyRegistrationOptions las opciones de WebAuthn para crear una llave
+ * @property {(input: {name: string, credential: any}) => Promise<AccountSecurityChange>} savePasskey
+ * @property {(input: {passkeyId: string, password: string}) => Promise<AccountSecurityChange>} removePasskey
+ * @property {(password: string) => Promise<AccountSecurityChange>} regenerateRecoveryCodes
+ * @property {() => Promise<AccountDeviceSession[]>} listSessions
+ * @property {() => Promise<number>} closeOtherSessions cuántas cerró
+ * @property {() => Promise<AccountEvent[]>} listActivity de lo más nuevo a lo más viejo
+ * @property {() => Promise<string|null>} [demoTotpCode] SOLO en la demostración: el código que enseñaría la app ahorita
+ *     (con él sale el botón «Usar el código de ejemplo»)
+ */
+/** Las funciones que todo conector trae (demoTotpCode es opcional: solo la demostración). */
+export declare const ACCOUNT_CONNECTOR_FUNCTIONS: readonly string[];
+/**
+ * Las funciones que le faltan al conector (un error de quien lo escribió: se avisa al arrancar, no al picar un botón).
+ *
+ * @param {object|null|undefined} connector
+ * @returns {string[]}
+ */
+export declare function missingConnectorFunctionsOf(connector: object | null | undefined): string[];

package/dist/types/account/demo/createDemoAccountConnector.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @param {object} [options]
+ * @param {{id: string, name: string, email: string, subtitle?: string, phone?: string}} [options.user] la persona de la
+ *     demostración; por omisión una inventada
+ * @param {string[]} [options.roles]
+ * @param {string[]} [options.abilities]
+ * @param {string[]} [options.labels] sus perfiles, ya traducidos (chips en Mi perfil)
+ * @param {string} [options.storageKey] dónde se recuerda la sesión en este navegador (con el nombre de la app)
+ * @param {(otpauthUrl: string) => Promise<string>} [options.toQrImageUrl] el QR de la clave (p. ej. QRCode.toDataURL de
+ *     la librería qrcode); sin él, la persona escribe la clave a mano en su app
+ * @param {string} [options.issuer] el nombre que enseña la app autenticadora
+ * @param {number} [options.delayMilliseconds] lo que tarda cada respuesta
+ * @returns {import('../accountConnector.js').AccountConnector}
+ */
+export declare function createDemoAccountConnector({ user, roles, abilities, labels, storageKey, toQrImageUrl, issuer, delayMilliseconds, }?: {
+    user?: {
+        id: string;
+        name: string;
+        email: string;
+        subtitle?: string;
+        phone?: string;
+    };
+    roles?: string[];
+    abilities?: string[];
+    labels?: string[];
+    storageKey?: string;
+    toQrImageUrl?: (otpauthUrl: string) => Promise<string>;
+    issuer?: string;
+    delayMilliseconds?: number;
+}): import('../accountConnector.js').AccountConnector;

package/dist/types/account/demo/totp.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Bytes → base32 (la clave como la escribe la persona en su app).
+ *
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+export declare function base32Of(bytes: Uint8Array): string;
+/**
+ * Base32 → bytes (sin espacios ni relleno).
+ *
+ * @param {string} text
+ * @returns {Uint8Array}
+ */
+export declare function bytesOfBase32(text: string): Uint8Array;
+/** Una clave nueva al azar, en base32. */
+export declare function newTotpSecret(): string;
+/**
+ * El código que enseña la app en ese momento.
+ *
+ * @param {string} secret la clave en base32
+ * @param {number} [timeMilliseconds] por omisión, ahora
+ * @param {number} [digits]
+ * @returns {Promise<string>}
+ */
+export declare function totpCodeAt(secret: string, timeMilliseconds?: number, digits?: number): Promise<string>;
+/**
+ * ¿El código es el de ahora (o el de un paso antes o después)?
+ *
+ * @param {string} secret
+ * @param {string} code los 6 dígitos
+ * @param {number} [timeMilliseconds]
+ * @returns {Promise<boolean>}
+ */
+export declare function isValidTotpCode(secret: string, code: string, timeMilliseconds?: number): Promise<boolean>;
+/**
+ * La dirección otpauth:// que va en el QR: la app la lee y guarda la cuenta con su clave.
+ *
+ * @param {{secret: string, account: string, issuer: string}} details
+ * @returns {string}
+ */
+export declare function otpauthUrlOf({ secret, account, issuer }: {
+    secret: string;
+    account: string;
+    issuer: string;
+}): string;

package/dist/types/account/restAccountConnector.d.ts

@@ -0,0 +1,49 @@
+/** Las rutas del contrato; se pegan a la baseUrl del cliente (/api + /auth/session). */
+export declare const ACCOUNT_REST_PATHS: Readonly<{
+    session: "/auth/session";
+    signIn: "/auth/sign-in";
+    secondStep: "/auth/second-step";
+    secondStepPasskeyOptions: "/auth/second-step/passkey-options";
+    secondStepPasskey: "/auth/second-step/passkey";
+    signOut: "/auth/sign-out";
+    forgotPassword: "/auth/forgot-password";
+    resetPassword: "/auth/reset-password";
+    profile: "/account";
+    password: "/account/password";
+    security: "/account/security";
+    totp: "/account/security/totp";
+    totpConfirm: "/account/security/totp/confirm";
+    passkeyRegistrationOptions: "/account/security/passkeys/registration-options";
+    passkeys: "/account/security/passkeys";
+    recoveryCodes: "/account/security/recovery-codes";
+    sessions: "/account/sessions";
+    closeOtherSessions: "/account/sessions/close-others";
+    activity: "/account/activity";
+}>;
+/**
+ * El estado de la verificación, del contrato a camelCase.
+ *
+ * @param {object} response
+ * @returns {import('./accountConnector.js').AccountSecurity}
+ */
+export declare function securityFromResponse(response: object): import('./accountConnector.js').AccountSecurity;
+/**
+ * Lo que regresa un cambio de seguridad: {security, recovery_codes?} → {security, recoveryCodes?}.
+ *
+ * @param {object} response
+ * @returns {import('./accountConnector.js').AccountSecurityChange}
+ */
+export declare function securityChangeFromResponse(response: object): import('./accountConnector.js').AccountSecurityChange;
+/**
+ * @param {{get: Function, post: Function, put: Function, delete: Function}} apiClient el de createApiClient
+ * @param {{paths?: Partial<Record<keyof typeof ACCOUNT_REST_PATHS, string>>}} [options] las rutas que se llaman distinto
+ * @returns {import('./accountConnector.js').AccountConnector}
+ */
+export declare function createRestAccountConnector(apiClient: {
+    get: Function;
+    post: Function;
+    put: Function;
+    delete: Function;
+}, { paths }?: {
+    paths?: Partial<Record<keyof typeof ACCOUNT_REST_PATHS, string>>;
+}): import('./accountConnector.js').AccountConnector;

package/dist/types/account-demo.d.ts

@@ -0,0 +1,2 @@
+export { createDemoAccountConnector } from './account/demo/createDemoAccountConnector.js';
+export { base32Of, bytesOfBase32, isValidTotpCode, newTotpSecret, otpauthUrlOf, totpCodeAt } from './account/demo/totp.js';

package/dist/types/account.d.ts

@@ -0,0 +1,16 @@
+export { ACCOUNT_CONNECTOR_FUNCTIONS, missingConnectorFunctionsOf } from './account/accountConnector.js';
+export { ACCOUNT_REST_PATHS, createRestAccountConnector, securityChangeFromResponse, securityFromResponse } from './account/restAccountConnector.js';
+export { default as AccountProvider, useAccount } from './account/AccountProvider.js';
+export { default as AccountSecuritySection } from './account/AccountSecuritySection.js';
+export { default as ForgotPasswordScreen } from './account/ForgotPasswordScreen.js';
+export { PROFILE_TAB, default as ProfileScreen } from './account/ProfileScreen.js';
+export { default as ResetPasswordScreen } from './account/ResetPasswordScreen.js';
+export { default as SignInScreen } from './account/SignInScreen.js';
+export type AccountConnector = import('./account/accountConnector.js').AccountConnector;
+export type AccountSession = import('./account/accountConnector.js').AccountSession;
+export type AccountUser = import('./account/accountConnector.js').AccountUser;
+export type AccountSecurity = import('./account/accountConnector.js').AccountSecurity;
+/** @typedef {import('./account/accountConnector.js').AccountConnector} AccountConnector */
+/** @typedef {import('./account/accountConnector.js').AccountSession} AccountSession */
+/** @typedef {import('./account/accountConnector.js').AccountUser} AccountUser */
+/** @typedef {import('./account/accountConnector.js').AccountSecurity} AccountSecurity */

package/dist/types/adapters/i18next.d.ts

@@ -0,0 +1,11 @@
+/**
+ * El traductor de ToolkitProvider sobre una instancia de i18next: si la llave existe en el proyecto regresa su texto;
+ * si no, undefined, y el paquete usa el suyo.
+ *
+ * @param {{exists: Function, t: Function}} i18n la instancia de i18next del proyecto
+ * @returns {(namespace: string, key: string, values?: object) => string|undefined}
+ */
+export declare function translateWithI18next(i18n: {
+    exists: Function;
+    t: Function;
+}): (namespace: string, key: string, values?: object) => string | undefined;

package/dist/types/adapters/nextNavigation.d.ts

@@ -0,0 +1,33 @@
+/**
+ * navigate(to) del framework con el router de Next.
+ *
+ * @returns {(to: string|number, options?: {replace?: boolean}) => void}
+ */
+declare function useNextNavigate(): (to: string | number, options?: {
+    replace?: boolean;
+}) => void;
+/**
+ * {pathname, search, key} de la página abierta.
+ *
+ * @returns {{pathname: string, search: string, key: string}}
+ */
+declare function useNextLocation(): {
+    pathname: string;
+    search: string;
+    key: string;
+};
+/**
+ * next/link con la prop `to` del framework.
+ *
+ * @param {{to?: string, href?: string}} props
+ */
+declare function NextToLink({ to, href, ...linkProps }: {
+    to?: string;
+    href?: string;
+}): import("react").JSX.Element;
+export declare const nextNavigation: Readonly<{
+    useNavigate: typeof useNextNavigate;
+    useLocation: typeof useNextLocation;
+    Link: typeof NextToLink;
+}>;
+export {};

package/dist/types/adapters/reactRouter.d.ts

@@ -0,0 +1,6 @@
+import { useLocation, useNavigate } from 'react-router';
+export declare const reactRouterNavigation: Readonly<{
+    useNavigate: typeof useNavigate;
+    useLocation: typeof useLocation;
+    Link: import("react").ForwardRefExoticComponent<import("react-router").LinkProps & import("react").RefAttributes<HTMLAnchorElement>>;
+}>;

package/dist/types/adapters/reactRouterRoutes.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Un grupo de rutas sin camino propio que pide permiso antes de pintar a sus hijas.
+ *
+ * @param {object|undefined} access la regla (accessRules.js); sin ella, el grupo es de todos
+ * @param {object[]} routes las rutas del módulo
+ * @returns {object} la ruta de react-router
+ */
+export declare function withAccess(access: object | undefined, routes: object[]): object;
+/**
+ * ¿Se está descargando la pantalla siguiente?
+ *
+ * @returns {boolean}
+ */
+export declare function useIsNavigating(): boolean;
+/**
+ * Las rutas con la recuperación de archivos viejos (staleChunks.js): cada `lazy`, también la de las hijas, recarga la
+ * página UNA vez si el archivo de su pantalla ya no existe porque se publicó otra versión. Lo demás de la ruta no cambia.
+ *
+ * @param {object[]} routes
+ * @returns {object[]}
+ */
+export declare function withChunkRecovery(routes: object[]): object[];
+/**
+ * La pantalla de error de una ruta (la que el router enseña cuando la pantalla truena o no se pudo descargar): una ruta
+ * que no existe es «Esta página no existe»; un archivo de otra versión, «Hay una versión nueva»; lo demás, «Algo falló de
+ * nuestro lado». Las dos últimas con su botón para recargar.
+ *
+ *   createBrowserRouter([{path: '/', element: <App />, ErrorBoundary: RouteErrorScreen, children: [...]}])
+ */
+export declare function RouteErrorScreen(): import("react").JSX.Element;

package/dist/types/api/ApiError.d.ts

@@ -0,0 +1,42 @@
+/** Los status que la pantalla suele tratar distinto, con su nombre. */
+export declare const API_ERROR_STATUS: Readonly<{
+    offline: 0;
+    unauthenticated: 401;
+    forbidden: 403;
+    notFound: 404;
+    conflict: 409;
+    gone: 410;
+    validation: 422;
+    tooManyRequests: 429;
+}>;
+export declare class ApiError extends Error {
+    status: number;
+    problem: object;
+    code: any;
+    title: string;
+    requestId: any;
+    retryAfterSeconds: number | null;
+    /**
+     * @param {object} details
+     * @param {number} details.status el status HTTP; 0 si no hubo respuesta
+     * @param {object|null} [details.problem] el cuerpo RFC 9457 del servidor ({title, detail, code, errors, request_id})
+     * @param {boolean} [details.translatedByServer] false si la respuesta llegó en otro idioma que el pedido
+     * @param {number|null} [details.retryAfterSeconds] 429: los segundos del header Retry-After
+     */
+    constructor({ status, problem, translatedByServer, retryAfterSeconds }: {
+        status: number;
+        problem?: object | null;
+        translatedByServer?: boolean;
+        retryAfterSeconds?: number | null;
+    });
+    /** No hubo respuesta del servidor (red caída, servidor apagado, se acabó el tiempo). */
+    get isOffline(): boolean;
+    /** Sin sesión, o se venció mientras se usaba la app. */
+    get isUnauthenticated(): boolean;
+    /** El registro no está en el estado que la acción necesita. */
+    get isConflict(): boolean;
+    /** La liga venció, ya se usó o no existe. */
+    get isGone(): boolean;
+    /** Errores de un formulario: los mensajes por campo van en problem.errors (fieldErrorsOf). */
+    get isValidation(): boolean;
+}