@jaws-developers-customers/consulca-types

Pacchetto NPM con tipi del dominio Consulca e helper pronti all'uso per date, valuta e oggetti principali derivati dallo schema MariaDB.

Installazione

npm install @jaws-developers-customers/consulca-types

Pubblicazione automatica

Ogni push su master esegue i test e pubblica automaticamente il pacchetto su npm tramite GitHub Actions.

Prerequisito:

• npm Trusted Publisher configurato nelle impostazioni del pacchetto su npm per l'organizzazione JAWS-Developers-Customers, il repository 15-NPMPackage e il workflow publish.yml (senza environment).

Il trusted publishing richiede npm 11.5.1 o successivo: il workflow installa npm 11.21.0 prima della pubblicazione, senza usare NPM_TOKEN. La versione npm 10 inclusa in Node.js 22 non supporta questa autenticazione, anche se può generare la provenance.

Il pacchetto viene sempre pubblicato con accesso pubblico. La visibilità del pacchetto npm è distinta da quella del repository GitHub: npm abilita automaticamente la provenance quando il token OIDC identifica un repository sorgente pubblico e il pacchetto è pubblico. Il workflow non forza --provenance, perché npm rifiuta la provenance di un repository identificato come privato con errore E422, anche se il pacchetto è pubblico. L'autenticazione OIDC rimane attiva anche senza provenance.

Il workflow genera una versione unica per ogni run su master, così la pubblicazione non fallisce per versioni duplicate.

Cosa esporta

• tipi TypeScript per le entità principali (User, Building, SingleBuilding, Apartment, Lease, Inspection, Claim, Work, ...)
• cataloghi ENUM dello schema (USER_ROLES, ACCESS_CHANNELS, ACCESS_ROLES, DEVICE_TYPES, ...)
• variabili CSS condivise importabili da colors.css e configurazione CONSTANTS, incluso il logo Base64
• helper:
  • formatDate
  • formatDateTime
  • formatCurrency
  • getUserFullName
  • formatAddress
  • hasUserRole
  • hasAccessChannel
  • Query.isSuccess

Colori e logo Consulca

Importa il foglio di stile nell'entrypoint della tua app (con un bundler che supporta gli import CSS):

import '@jaws-developers-customers/consulca-types/colors.css';

Il foglio definisce le costanti come variabili CSS globali in :root, utilizzabili con var(...). La palette usa i valori esadecimali per il web indicati in Loghi Consulca.pdf:

| Variabile | Colore | Utilizzo | | --- | --- | --- | | --color-primary | #2D2F7F | Blu Consulca: pulsanti principali, link e intestazioni | | --color-secondary | #C8D9F1 | Azzurro Consulca: sfondi secondari e selezioni | | --color-accent | #CAC8CA | Grigio Consulca: bordi ed elementi decorativi | | --color-background | #F7F9FB | Fondo neutro dell'interfaccia, mantenuto dalla palette precedente e non definito nel PDF | | --color-text | #2D2F7F | Testo principale in blu Consulca |

.header {
  background-color: var(--color-secondary);
  color: var(--color-text);
}

L'oggetto JavaScript immutabile COLOR_PALETTE rimane disponibile per compatibilita' con i progetti esistenti. CONSTANTS rimane disponibile sia con require sia con import.

I nomi della palette rimangono invariati per i progetti esistenti, ma i colori cambiano: in particolare accent non e' piu' rosso e non va usato per indicare errori. La palette del marchio non definisce colori semantici per errori, avvisi o successi.

CONSTANTS.LOGO e' una data URI PNG Base64 del logo completo (simbolo e scritta), estratto dal PDF a 940 x 216 pixel con fondo trasparente. Non richiede richieste di rete o conversioni nel browser. CONSTANTS.ICON conserva l'URL dell'icona esistente; CONSTANTS.API e CONSTANTS.API_DEV restano invariati.

Utilizzo in React

import '@jaws-developers-customers/consulca-types/colors.css';
import { CONSTANTS } from '@jaws-developers-customers/consulca-types';

export function Header() {
  return (
    <header style={{ backgroundColor: 'var(--color-secondary)', color: 'var(--color-text)' }}>
      <img
        src={CONSTANTS.LOGO}
        alt="Consulca SA"
        style={{ width: 240, maxWidth: '100%', height: 'auto' }}
      />
    </header>
  );
}

Se il progetto usa una Content Security Policy, la direttiva img-src deve consentire data:.

Esempio

const {
  formatCurrency,
  formatDate,
  getUserFullName,
  hasUserRole,
} = require('@jaws-developers-customers/consulca-types');

console.log(formatDate('2026-09-16T10:30:00Z'));
console.log(formatCurrency(1250.5));
console.log(getUserFullName({ first_name: 'Mario', last_name: 'Rossi' }));
console.log(hasUserRole([{ role: 'manager' }], 'manager'));

Query.isSuccess(error_code) restituisce true per i codici nel formato xx.xx.xxx il cui ultimo gruppo inizia con 0.

Esempio TypeScript

import {
  formatDateTime,
  type Inspection,
  type User,
} from '@jaws-developers-customers/consulca-types';

const user: User = {
  id: 'uuid',
  email: '[email protected]',
  first_name: 'Mario',
  last_name: 'Rossi',
  status: 'active',
  country_code: 'CH',
  access_channels: [{
    channel: 'intranet_dashboard',
    role: 'employee',
    status: 'active',
    created_at: '2026-10-05 18:29:50',
    revoked_at: null,
  }],
};

const inspection: Inspection = {
  id: 'uuid',
  lease_id: 'lease-id',
  inspector_id: user.id,
  inspection_type: 'move_in',
  status: 'draft',
  created_at: new Date(),
  updated_at: new Date(),
};

console.log(formatDateTime(inspection.created_at, 'it-CH'));

User accetta direttamente i dati di /user/get/me: password_hash, created_at e updated_at non sono obbligatori. Non salvare la password o il suo hash nello stato client. I canali sono contenuti in user.access_channels, senza richiedere user_id per ogni elemento; AccessChannelAssignment rappresenta invece una riga della tabella con user_id obbligatorio.

USER_ROLES descrive i ruoli della tabella user_roles (lessor, manager, website_manager, inspector), mentre ACCESS_ROLES descrive i ruoli di access_channels e user_invites. Per verificare l'accesso usa hasAccessChannel(user.access_channels, 'intranet_dashboard'): i canali revocati vengono esclusi.

I cataloghi dei ruoli e i relativi tipi TypeScript sono verificati dai test rispetto agli ENUM di consulca(4).sql, inclusi i ruoli di gestione di apartment_managers.

Apartment include anche size e area_m2, opzionali per compatibilità con i dati esistenti: entrambi accettano numeri, stringhe decimali restituite dal driver MariaDB oppure null. Sono disponibili anche tramite l'alias Property e negli appartamenti di SingleBuilding. Questi due campi non sono presenti nel dump SQL incluso.

I riferimenti agli appartamenti usano apartment_id, Apartment usa apartment_number e gli allegati delle ispezioni usano inspection_item_id. ApartmentRoom include anche custom_name, m2 e size; Lease.user_id è nullable. SingleBuilding include tutti i campi di Building e l'array apartments. Edifici e appartamenti hanno stato active o archived. Property rimane disponibile come alias retrocompatibile di Apartment. Sono disponibili anche Device, UserInvite, Room, ApartmentRoom e ApartmentManager. I campi SQL nullable accettano null; i decimali accettano numeri o stringhe restituiti dal driver MariaDB.

Room include il campo opzionale checklist restituito dall'API della stanza singola: un array di RoomChecklistItem con id, room_id, name, sort_order numerico e active booleano o numerico (ad esempio 0 o 1). L'array può essere vuoto; il campo resta opzionale per compatibilità con le stanze senza checklist.