@utilia-os/sdk-js 1.7.0 → 2.1.0

package/README.md

@@ -179,6 +179,174 @@ console.log(stats.bySeverity);   // { critical: 5, high: 10, ... }
 console.log(stats.byModule);     // { auth: 3, payments: 7, ... }
 ```
 
+### Configuración pública de la organización
+
+Desde la versión 1.10.0, puedes leer los datos públicos de la organización
+(branding, valores fiscales por defecto, contacto) sin necesidad de permisos
+de administración. Útil para auto-rellenar formularios de presupuestos,
+conocer el impuesto local del tenant o mostrar el logo en un portal externo:
+
+```typescript
+const settings = await sdk.organizationSettings.getPublicSettings();
+
+console.log(settings.companyName);        // "UTILIA"
+console.log(settings.defaultCurrency);    // "EUR"
+console.log(settings.defaultTaxName);     // "IVA"
+console.log(settings.defaultTaxRate);     // 21
+console.log(settings.country);            // "ES"
+console.log(settings.timezone);           // "Atlantic/Canary"
+console.log(settings.logoUrl);            // URL presignada fresca
+```
+
+Campos incluidos: identidad corporativa, domicilio social y operativo,
+canales de contacto dinámicos, datos bancarios, configuración fiscal por
+defecto (impuesto, tasa, país, moneda), timezone, branding (colores, logos)
+y la configuración visual personalizada para PDFs de presupuestos.
+
+Los metadatos internos (id, createdAt, updatedAt, updatedById) y los emails
+legacy (emailSupport, emailHr, etc.) no se exponen en esta respuesta; los
+emails legacy se transforman automáticamente a `contactChannels` por
+retrocompatibilidad.
+
+> **Breaking change en v2.0.0**: se ha eliminado el campo `businessActivity`
+> de `OrganizationPublicSettings`. La actividad económica ya no forma parte
+> de la configuración general de la organización; se ha migrado al modelo
+> `FiscalConfig.activityDesc`, disponible vía el endpoint
+> `finance/fiscal-config` (se añadirá un método dedicado al SDK en próximas
+> versiones). Si tu integración leía `settings.businessActivity`, debes
+> migrar a la nueva ubicación.
+
+## Comentarios y firmas de presupuestos
+
+Desde la versión 2.1.0, el SDK cubre los dos dominios centrales del flujo de
+aprobación de presupuestos: la conversación entre equipo y cliente y la firma
+electrónica con magic link.
+
+### Comentarios (`sdk.budgetComments`)
+
+Dos visibilidades: `INTERNAL` (solo equipo) y `CLIENT` (visible también en el
+portal del cliente). Las menciones con `mentionedUserIds` solo tienen efecto
+cuando la visibilidad es `INTERNAL`.
+
+```typescript
+import { UtiliaSDK } from '@utilia-os/sdk-js';
+
+const sdk = new UtiliaSDK({ baseURL: 'https://os.utilia.ai/api', apiKey: '...' });
+
+// Listar comentarios dirigidos al cliente
+const page = await sdk.budgetComments.list(budgetId, {
+  visibility: 'CLIENT',
+  page: 1,
+  limit: 20,
+});
+
+// Crear un comentario interno con menciones
+const comment = await sdk.budgetComments.create(budgetId, {
+  body: 'Revisar el descuento del item 2 antes de enviar al cliente.',
+  visibility: 'INTERNAL',
+  mentionedUserIds: ['6d1a4c6b-3f8b-4a0e-a0d1-b29f1f1c21cb'],
+});
+
+// Editar el propio comentario
+await sdk.budgetComments.update(budgetId, comment.id, {
+  body: 'Revisar descuento y condiciones de pago.',
+});
+
+// Crear varios comentarios en lote, tolerante a fallos
+const result = await sdk.budgetComments.bulkCreate(
+  budgetId,
+  [
+    { body: 'Primer comentario' },
+    { body: 'Segundo comentario', clientOperationId: 'op-2' },
+  ],
+  { idempotencyKey: 'migration-2026-04-17' },
+);
+console.log(result.summary); // { total: 2, ok: 2, failed: 0 }
+```
+
+### Firmas y magic link (`sdk.budgetSignatures`)
+
+El flujo completo cubre la emisión del magic link, el listado y revocación, la
+verificación de integridad de una firma ya registrada y la descarga del
+certificado legal.
+
+```typescript
+// Emitir un magic link (idempotente por email)
+const link = await sdk.budgetSignatures.generateSigningLink(budgetId, {
+  signerEmail: 'cliente@empresa.com',
+  signerName: 'María García',
+  expiresInHours: 72,
+  sendEmail: true,
+});
+
+if (!link.reused && link.signingUrl) {
+  console.log('Enviar al cliente:', link.signingUrl);
+}
+
+// Listar los magic links vivos
+const activeLinks = await sdk.budgetSignatures.listSigningLinks(budgetId);
+
+// Revocar un link
+await sdk.budgetSignatures.revokeSigningLink(budgetId, link.tokenId);
+
+// Verificar la integridad de una firma ya registrada
+const signatures = await sdk.budgetSignatures.list(budgetId);
+const verification = await sdk.budgetSignatures.verify(
+  budgetId,
+  signatures[0].id,
+);
+if (!verification.valid) {
+  console.warn('El documento ha cambiado después de la firma.');
+}
+
+// Descargar el certificado legal
+const pdf = await sdk.budgetSignatures.downloadCertificate(
+  budgetId,
+  signatures[0].id,
+);
+```
+
+### Audit trail
+
+Historial paginado de eventos del proceso de firma (emisión, visualización,
+descarga del PDF, aprobación, rechazo, expiración, revocación y fallos):
+
+```typescript
+const events = await sdk.budgetSignatures.getAuditTrail(budgetId, {
+  tokenId: link.tokenId,
+  limit: 100,
+});
+```
+
+## OAuth y Sign In
+
+Desde la versión 1.6.0, el SDK incluye soporte nativo para OAuth 2.1 con PKCE. Esto permite implementar "Iniciar sesión con UTILIA" en tu aplicación:
+
+```typescript
+const sdk = new UtiliaSDK({
+  baseURL: 'https://os.utilia.ai/api',
+  oauth: {
+    clientId: 'client_xxxxxxxxxx',
+    redirectUri: 'http://localhost:3000/callback',
+    scopes: ['openid', 'profile', 'email'],
+  },
+});
+
+// Redirigir al usuario para autorizar
+const authUrl = await sdk.oauth.getAuthorizationUrl();
+window.location.href = authUrl;
+
+// Opcionalmente, solicitar un tema específico para la pantalla de consentimiento
+const darkUrl = await sdk.oauth.getAuthorizationUrl({ theme: 'dark' });
+window.location.href = darkUrl;
+
+// En la página de callback
+const tokens = await sdk.oauth.handleCallback(code);
+const userInfo = await sdk.oauth.getUserInfo();
+```
+
+Documentación completa: https://os.utilia.ai/dashboard/docs/integraciones-sdk/sdk-js-guia-oauth
+
 ## Manejo de Errores
 
 ```typescript