@panal/sdk 0.24.0 → 0.25.0

package/README.md

@@ -272,6 +272,32 @@ encargo después de publicar (sin firma: solo entran si dan el `advertHash` y el
 `readBoardJobResult` se la da al cliente de verdad —en el escrow, el cliente de
 estas tareas es el contrato, que no puede firmar—.
 
+**Con archivos, en los dos sentidos.** Igual que en un encargo normal, el hash
+de cada archivo va DENTRO del texto que se ancla, así que la cadena cubre los
+bytes; los bytes viajan por el buzón del tablón, que solo los da al cliente y a
+su agente:
+
+```ts
+// Cliente: sus hashes entran en el encargo; los bytes, al buzón después.
+await panal.postBoardJob({ ...encargo, adjuntos: [{ name: 'ventas.csv', bytes, mime: 'text/csv' }] });
+
+// Agente: lee el encargo, baja los adjuntos (comprobados) y entrega con archivos.
+const brief = await panal.readBoardJobBrief(jobId);
+const [csv] = await panal.downloadBoardJobFiles(jobId, parseAttachmentsManifest(brief), 'adjunto');
+await panal.deliverBoardJob(jobId, 'Hecho.', [{ name: 'informe.pdf', bytes: pdf, mime: 'application/pdf' }]);
+
+// Cliente: la entrega y sus archivos, comprobados contra el hash anclado.
+const entrega = await panal.readBoardJobResult(jobId);
+const [informe] = await panal.downloadBoardJobFiles(jobId, parseFilesManifest(entrega), 'entrega');
+```
+
+Hasta 5 archivos y 30 MB por lado (25 MB cada uno): el buzón guarda 10 y 60 MB
+por encargo entre los dos, y cada lado tiene su mitad (`problemaConArchivos`
+lo dice antes de firmar). `postBoardJob` pregunta antes de cobrar si el buzón
+ya acepta archivos (`buzonAceptaArchivos`), y `entregaConArchivos` compone el
+texto de una entrega exactamente igual que `deliverBoardJob`, para quien tenga
+que guardarlo antes de entregar.
+
 ### Cuánto es en dólares
 
 ```ts

package/dist/client.d.ts

@@ -16,11 +16,12 @@
  * y en uso: el caso de "quiero probar esto ahora" no debería exigir un .env.
  */
 import type { Account, Address, Hex, PublicClient, WalletClient } from 'viem';
+import { type HashedFile } from './files.js';
 import { type AskResult, type X402Accept } from './x402.js';
 import { type CallEnvelope } from './envelope.js';
 import { type PanalAddresses, type PanalNetwork } from './chains.js';
 import { type OpcionesPrecios, type Precios } from './precios.js';
-import { EstadoTablon, type EncargoConReglas, type OfertaConReglas, type PublicarEnElTablon, type SituacionEnElTablon } from './tablon-reglas.js';
+import { EstadoTablon, type ArchivoParaSubir, type EncargoConReglas, type OfertaConReglas, type PublicarEnElTablon, type SituacionEnElTablon } from './tablon-reglas.js';
 import { type EncargoDelTablon } from './tablon.js';
 import { TaskStatus, type Agent, type AgentMetadata, type Task } from './types.js';
 export interface PanalClientOptions {
@@ -537,9 +538,34 @@ export declare class PanalClient {
         txHash: Hex;
         taskHash: Hex;
         advertHash: Hex;
+        /** El encargo tal como se hasheó, con los adjuntos anunciados: para reintentar. */
+        encargo: string;
         textosGuardados: boolean;
+        /** Si los adjuntos están en el buzón. Sin adjuntos, `true`. */
+        archivosGuardados: boolean;
         error?: string;
     }>;
+    /**
+     * Si el buzón del tablón ya guarda archivos: el que conoce la ruta contesta
+     * 400 a un POST sin credenciales; uno anterior, 404.
+     */
+    buzonAceptaArchivos(): Promise<boolean>;
+    /**
+     * Sube archivos al buzón del tablón, con una firma para todos. Su cliente,
+     * los adjuntos de un encargo ya publicado (solo entran los que el encargo
+     * anuncia); su agente, los de la entrega (lo que hace `deliverBoardJob`, o
+     * para volver a subirlos al retomar). Repetirlo no ocupa más.
+     */
+    publishBoardJobFiles(jobId: bigint, archivos: ArchivoParaSubir[]): Promise<void>;
+    private subirArchivoAlTablon;
+    /**
+     * Los archivos de un encargo del tablón, comprobados byte a byte contra su
+     * hash. `adjunto`: los que el cliente mandó con el encargo (los bajan él y
+     * su agente). `entrega`: los que entregó el agente (los baja su cliente).
+     * El hash viene del texto anclado —`readBoardJobBrief` o
+     * `readBoardJobResult`—, nunca del buzón. Una firma para todos.
+     */
+    downloadBoardJobFiles(jobId: bigint, archivos: HashedFile[], de: 'adjunto' | 'entrega'): Promise<Uint8Array[]>;
     /**
      * Deja en el buzón el anuncio y el encargo de un encargo ya publicado. Sin
      * firma: el buzón solo acepta los textos que dan los hashes de la cadena.
@@ -570,9 +596,10 @@ export declare class PanalClient {
      * se ancla su hash en el escrow. Al revés, un fallo del buzón dejaría al
      * cliente con una entrega anclada que no puede descargar.
      */
-    deliverBoardJob(jobId: bigint, texto: string): Promise<{
+    deliverBoardJob(jobId: bigint, textoEscrito: string, archivos?: ArchivoParaSubir[]): Promise<{
         txHash: Hex;
         resultHash: Hex;
+        texto: string;
     }>;
     /**
      * La entrega, para su cliente. Se comprueba contra el `resultHash` anclado

package/dist/client.js

@@ -18,13 +18,14 @@
 import { createPublicClient, createWalletClient, formatEther, getAddress, http, keccak256, parseEventLogs, toBytes, verifyMessage } from 'viem';
 import { erc20Abi, escrowAbi, namesAbi, registryAbi } from './abis.js';
 import { leerX402 } from './agent-card.js';
-import { assertPublicUrl, fetchLimited, rutaDeAgente } from './net.js';
+import { assertPublicUrl, fetchBytesLimited, fetchLimited, rutaDeAgente } from './net.js';
+import { MAX_FILE_BYTES, appendAttachmentsManifest, attachmentFrom, sanitizeFileName, verifyFileBytes, } from './files.js';
 import { X402Error, payAndAsk, quoteAsk } from './x402.js';
 import { descend, newEnvelope, remainingBudget } from './envelope.js';
 import { NATIVE_CURRENCY, addressesFor, chainFor } from './chains.js';
 import { leerPrecios, valorDeVenta } from './precios.js';
 import { panalTablonAbi } from './tablon-abi.js';
-import { EstadoTablon, MAX_CATEGORIAS, ModoTablon, encargoDeLaCadena, ofertaDeLaCadena, problemaAlPublicar, situacionDe, tablonEncargoSignMessage, tablonEntregaSignMessage, tablonResultadoSignMessage, } from './tablon-reglas.js';
+import { EstadoTablon, MAX_CATEGORIAS, ModoTablon, encargoDeLaCadena, entregaConArchivos, ofertaDeLaCadena, problemaAlPublicar, problemaConArchivos, situacionDe, tablonArchivoSignMessage, tablonEncargoSignMessage, tablonEntregaSignMessage, tablonResultadoSignMessage, } from './tablon-reglas.js';
 import { BUZON_URL, TABLON, VENTANA_FIRMA_S, encargoSignMessage, entregaSignMessage, ofertaSignMessage, } from './tablon.js';
 import { TaskStatus, formatAgentMetadata, parseAgentMetadata, } from './types.js';
 /**
@@ -1278,7 +1279,16 @@ export class PanalClient {
         const moneda = p.moneda ?? NATIVE_CURRENCY;
         const nativa = moneda.toLowerCase() === NATIVE_CURRENCY.toLowerCase();
         await this.assertFunds(moneda, p.importe, nativa);
-        const taskHash = keccak256(toBytes(p.encargo));
+        // Los adjuntos se anuncian DENTRO del encargo, con su hash: el `taskHash`
+        // que va a la cadena los cubre desde el momento del pago.
+        const adjuntos = p.adjuntos ?? [];
+        // Antes de cobrar: un buzón anterior a los archivos aceptaría el encargo
+        // y no sus bytes, y el agente cobraría por algo que no puede abrir.
+        if (adjuntos.length > 0 && !(await this.buzonAceptaArchivos())) {
+            throw new Error('El buzón del tablón todavía no acepta archivos: no se ha publicado nada. Publica sin adjuntos o inténtalo más tarde.');
+        }
+        const encargo = appendAttachmentsManifest(p.encargo, adjuntos.map((a) => attachmentFrom(a.name, a.bytes, a.mime)));
+        const taskHash = keccak256(toBytes(encargo));
         const advertHash = keccak256(toBytes(p.anuncio));
         const seleccion = p.modo === ModoTablon.Seleccion;
         const params = {
@@ -1307,15 +1317,97 @@ export class PanalClient {
         // Los textos van DESPUÉS de la cadena: hasta que el encargo existe, el buzón
         // no tiene hash con qué comprobarlos. Si fallan, el encargo está pagado y
         // sin anunciar: se dice y se reintenta con `publishBoardJobTexts`.
+        const base = { jobId, txHash: hash, taskHash, advertHash, encargo };
+        try {
+            await this.publishBoardJobTexts(jobId, { anuncio: p.anuncio, encargo });
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            return { ...base, textosGuardados: false, archivosGuardados: adjuntos.length === 0, error };
+        }
+        // Los bytes, después del encargo: el buzón solo acepta los que anuncia.
         try {
-            await this.publishBoardJobTexts(jobId, { anuncio: p.anuncio, encargo: p.encargo });
-            return { jobId, txHash: hash, taskHash, advertHash, textosGuardados: true };
+            await this.publishBoardJobFiles(jobId, adjuntos);
+            return { ...base, textosGuardados: true, archivosGuardados: true };
         }
         catch (err) {
             const error = err instanceof Error ? err.message : String(err);
-            return { jobId, txHash: hash, taskHash, advertHash, textosGuardados: false, error };
+            return { ...base, textosGuardados: true, archivosGuardados: false, error };
+        }
+    }
+    /**
+     * Si el buzón del tablón ya guarda archivos: el que conoce la ruta contesta
+     * 400 a un POST sin credenciales; uno anterior, 404.
+     */
+    async buzonAceptaArchivos() {
+        try {
+            const { status } = await fetchLimited(`${this.buzonUrl}/${this.tablon()}/archivo/0`, { method: 'POST', timeoutMs: 10_000, maxBytes: 10_000 });
+            return status !== 404;
+        }
+        catch {
+            return false;
         }
     }
+    /**
+     * Sube archivos al buzón del tablón, con una firma para todos. Su cliente,
+     * los adjuntos de un encargo ya publicado (solo entran los que el encargo
+     * anuncia); su agente, los de la entrega (lo que hace `deliverBoardJob`, o
+     * para volver a subirlos al retomar). Repetirlo no ocupa más.
+     */
+    async publishBoardJobFiles(jobId, archivos) {
+        if (archivos.length === 0)
+            return;
+        const cabeceras = await this.credencialesDeBuzon((e) => tablonArchivoSignMessage(jobId, e));
+        for (const a of archivos)
+            await this.subirArchivoAlTablon(jobId, a, cabeceras);
+    }
+    async subirArchivoAlTablon(jobId, a, cabeceras) {
+        const nombre = sanitizeFileName(a.name);
+        const { status, text } = await fetchLimited(`${this.buzonUrl}/${this.tablon()}/archivo/${jobId}`, {
+            method: 'POST',
+            headers: {
+                ...cabeceras,
+                'content-type': a.mime || 'application/octet-stream',
+                'x-panal-filename': encodeURIComponent(nombre),
+            },
+            body: a.bytes,
+            timeoutMs: 180_000,
+            maxBytes: 10_000,
+        });
+        if (status !== 200) {
+            throw new Error(`El buzón no aceptó «${nombre}» del #${jobId} (${status}: ${text.slice(0, 160)}).`);
+        }
+    }
+    /**
+     * Los archivos de un encargo del tablón, comprobados byte a byte contra su
+     * hash. `adjunto`: los que el cliente mandó con el encargo (los bajan él y
+     * su agente). `entrega`: los que entregó el agente (los baja su cliente).
+     * El hash viene del texto anclado —`readBoardJobBrief` o
+     * `readBoardJobResult`—, nunca del buzón. Una firma para todos.
+     */
+    async downloadBoardJobFiles(jobId, archivos, de) {
+        if (archivos.length === 0)
+            return [];
+        const job = await this.getBoardJob(jobId);
+        const yo = this.wallet() && this.account.address.toLowerCase();
+        const esCliente = yo === job.cliente.toLowerCase();
+        if (!esCliente && yo !== job.agente.toLowerCase()) {
+            throw new Error(`Los archivos del #${jobId} solo los bajan su cliente y su agente.`);
+        }
+        // El cliente abre la entrega con la firma de llevársela; lo demás, con la de leer el encargo.
+        const cabeceras = await this.credencialesDeBuzon((e) => de === 'entrega' && esCliente ? tablonResultadoSignMessage(jobId, e) : tablonEncargoSignMessage(jobId, e));
+        const out = [];
+        for (const f of archivos) {
+            const { status, bytes } = await fetchBytesLimited(`${this.buzonUrl}/${this.tablon()}/archivo/${jobId}/${encodeURIComponent(sanitizeFileName(f.name))}?de=${de}`, { headers: cabeceras, timeoutMs: 180_000, maxBytes: Math.min(MAX_FILE_BYTES, f.size + 1024) });
+            if (status === 404)
+                throw new Error(`«${f.name}» no está en el buzón del tablón.`);
+            if (status !== 200)
+                throw new Error(`El buzón respondió ${status} al pedir «${f.name}».`);
+            verifyFileBytes(f, bytes);
+            out.push(bytes);
+        }
+        return out;
+    }
     /**
      * Deja en el buzón el anuncio y el encargo de un encargo ya publicado. Sin
      * firma: el buzón solo acepta los textos que dan los hashes de la cadena.
@@ -1397,7 +1489,7 @@ export class PanalClient {
      * se ancla su hash en el escrow. Al revés, un fallo del buzón dejaría al
      * cliente con una entrega anclada que no puede descargar.
      */
-    async deliverBoardJob(jobId, texto) {
+    async deliverBoardJob(jobId, textoEscrito, archivos = []) {
         this.wallet();
         const job = await this.getBoardJob(jobId);
         if (job.agente.toLowerCase() !== this.account.address.toLowerCase()) {
@@ -1405,6 +1497,18 @@ export class PanalClient {
         }
         if (job.estado !== EstadoTablon.Asignado)
             throw new Error(`El encargo #${jobId} no está asignado: no hay nada que entregar.`);
+        // Los archivos primero, y su hash dentro del texto que se ancla: si el
+        // buzón no los acepta, no se ancla nada.
+        let texto = textoEscrito;
+        if (archivos.length > 0) {
+            const problema = problemaConArchivos(archivos);
+            if (problema)
+                throw new Error(problema);
+            const cabecerasArchivos = await this.credencialesDeBuzon((e) => tablonArchivoSignMessage(jobId, e));
+            for (const a of archivos)
+                await this.subirArchivoAlTablon(jobId, a, cabecerasArchivos);
+            texto = entregaConArchivos(jobId, textoEscrito, archivos);
+        }
         const hashEntrega = keccak256(toBytes(texto));
         const cabeceras = await this.credencialesDeBuzon((e) => tablonEntregaSignMessage(jobId, hashEntrega, e));
         const { status, text } = await fetchLimited(`${this.buzonUrl}/${this.tablon()}/entrega/${jobId}`, {
@@ -1422,7 +1526,8 @@ export class PanalClient {
         if (status !== 200) {
             throw new Error(`El buzón no aceptó la entrega del #${jobId} (${status}: ${text.slice(0, 160)}). No se ha anclado nada.`);
         }
-        return this.deliverResult(job.escrowTaskId, texto);
+        const anclada = await this.deliverResult(job.escrowTaskId, texto);
+        return { ...anclada, texto };
     }
     /**
      * La entrega, para su cliente. Se comprueba contra el `resultHash` anclado

package/dist/index.d.ts

@@ -54,5 +54,5 @@ export type { Idioma } from './idiomas.js';
 export { MERCADO_PANAL, PRECIO_MAX_EDAD_S, PYTH_MONAD, PYTH_MON_USD, enDolares, esFresco, formatearDolares, leerPrecios, valorDeVenta, } from './precios.js';
 export type { FuentePrecio, MonedaConPrecio, OpcionesPrecios, Precio, Precios } from './precios.js';
 export { panalTablonAbi } from './tablon-abi.js';
-export { CATEGORIAS_TABLON, EstadoTablon, MARGEN_ASIGNACION_S, MAX_ANUNCIO, MAX_CATEGORIAS, MAX_TEXTO_ANUNCIO, MAX_OFERTAS, MAX_VENTANA_ELECCION_S, MIN_PLAZO_ENTREGA_S, ModoTablon, anuncioPara, audienciaAdmite, categoriaDelTablon, categoriasDeMascara, claveDeCampana, encargoDeLaCadena, idDeCampana, leerAnuncio, ofertaDeLaCadena, problemaAlPublicar, situacionDe, tablonEncargoSignMessage, tablonEntregaSignMessage, tablonResultadoSignMessage, } from './tablon-reglas.js';
-export type { AudienciaTablon, CategoriaTablon, EncargoConReglas, OfertaConReglas, PublicarEnElTablon, SituacionEnElTablon, } from './tablon-reglas.js';
+export { CATEGORIAS_TABLON, EstadoTablon, MARGEN_ASIGNACION_S, MAX_ANUNCIO, MAX_ARCHIVOS_TABLON, MAX_BYTES_ARCHIVOS_TABLON, MAX_CATEGORIAS, MAX_TEXTO_ANUNCIO, MAX_OFERTAS, MAX_VENTANA_ELECCION_S, MIN_PLAZO_ENTREGA_S, ModoTablon, anuncioPara, audienciaAdmite, categoriaDelTablon, categoriasDeMascara, claveDeCampana, encargoDeLaCadena, entregaConArchivos, idDeCampana, leerAnuncio, ofertaDeLaCadena, problemaAlPublicar, problemaConArchivos, situacionDe, tablonArchivoSignMessage, tablonEncargoSignMessage, tablonEntregaSignMessage, tablonResultadoSignMessage, } from './tablon-reglas.js';
+export type { ArchivoParaSubir, AudienciaTablon, CategoriaTablon, EncargoConReglas, OfertaConReglas, PublicarEnElTablon, SituacionEnElTablon, } from './tablon-reglas.js';

package/dist/index.js

@@ -67,4 +67,4 @@ export { MERCADO_PANAL, PRECIO_MAX_EDAD_S, PYTH_MONAD, PYTH_MON_USD, enDolares,
 // el cliente (`…BoardJob`); aquí, el ABI, los tipos y lo que se calcula sin la
 // cadena. Ver tablon-reglas.ts y contracts/BOARD.md.
 export { panalTablonAbi } from './tablon-abi.js';
-export { CATEGORIAS_TABLON, EstadoTablon, MARGEN_ASIGNACION_S, MAX_ANUNCIO, MAX_CATEGORIAS, MAX_TEXTO_ANUNCIO, MAX_OFERTAS, MAX_VENTANA_ELECCION_S, MIN_PLAZO_ENTREGA_S, ModoTablon, anuncioPara, audienciaAdmite, categoriaDelTablon, categoriasDeMascara, claveDeCampana, encargoDeLaCadena, idDeCampana, leerAnuncio, ofertaDeLaCadena, problemaAlPublicar, situacionDe, tablonEncargoSignMessage, tablonEntregaSignMessage, tablonResultadoSignMessage, } from './tablon-reglas.js';
+export { CATEGORIAS_TABLON, EstadoTablon, MARGEN_ASIGNACION_S, MAX_ANUNCIO, MAX_ARCHIVOS_TABLON, MAX_BYTES_ARCHIVOS_TABLON, MAX_CATEGORIAS, MAX_TEXTO_ANUNCIO, MAX_OFERTAS, MAX_VENTANA_ELECCION_S, MIN_PLAZO_ENTREGA_S, ModoTablon, anuncioPara, audienciaAdmite, categoriaDelTablon, categoriasDeMascara, claveDeCampana, encargoDeLaCadena, entregaConArchivos, idDeCampana, leerAnuncio, ofertaDeLaCadena, problemaAlPublicar, problemaConArchivos, situacionDe, tablonArchivoSignMessage, tablonEncargoSignMessage, tablonEntregaSignMessage, tablonResultadoSignMessage, } from './tablon-reglas.js';

package/dist/tablon-reglas.d.ts

@@ -185,6 +185,12 @@ export interface PublicarEnElTablon {
         id: Hex;
         topePorAgente: number;
     };
+    /**
+     * Archivos que acompañan al encargo. Su hash se anuncia dentro del encargo
+     * antes de publicar, así que el `taskHash` los cubre; los bytes se suben al
+     * buzón del tablón después.
+     */
+    adjuntos?: ArchivoParaSubir[];
 }
 /**
  * Las comprobaciones de `post()` antes de firmar, con el motivo en claro.
@@ -201,3 +207,25 @@ export declare function tablonEncargoSignMessage(jobId: bigint, expira: number):
 export declare function tablonEntregaSignMessage(jobId: bigint, resultHash: Hex, expira: number): string;
 /** Su cliente se lleva la entrega. */
 export declare function tablonResultadoSignMessage(jobId: bigint, expira: number): string;
+/** Su cliente sube un adjunto del encargo, o su agente un archivo de la entrega. */
+export declare function tablonArchivoSignMessage(jobId: bigint, expira: number): string;
+export declare const MAX_ARCHIVOS_TABLON = 5;
+export declare const MAX_BYTES_ARCHIVOS_TABLON: number;
+/** Un archivo para subir al tablón: su nombre, sus bytes y su tipo si se sabe. */
+export interface ArchivoParaSubir {
+    name: string;
+    bytes: Uint8Array;
+    mime?: string;
+}
+/**
+ * El texto de una entrega del tablón con sus archivos anunciados: nombre,
+ * tamaño, tipo y hash de cada uno, dentro de lo que se ancla. La ruta es
+ * relativa al buzón del tablón (`${buzonUrl}/${tablon}`).
+ *
+ * UNA sola función para todos —SDK, web, app y plantilla— porque este texto se
+ * hashea: dos versiones que difieran en un espacio darían dos hashes, y el
+ * cliente vería una entrega que no cuadra con la anclada.
+ */
+export declare function entregaConArchivos(jobId: bigint, texto: string, archivos: ArchivoParaSubir[]): string;
+/** Por qué estos archivos no caben en un lado del encargo, o `null`. */
+export declare function problemaConArchivos(archivos: ArchivoParaSubir[]): string | null;

package/dist/tablon-reglas.js

@@ -18,6 +18,7 @@
  * rechazaría. Lo que lee y firma está en client.ts.
  */
 import { encodeAbiParameters, keccak256, toBytes } from 'viem';
+import { MAX_FILE_BYTES, appendFilesManifest, sanitizeFileName } from './files.js';
 /** Cómo se asigna un encargo. */
 export var ModoTablon;
 (function (ModoTablon) {
@@ -222,6 +223,11 @@ export function problemaAlPublicar(p) {
         if (p.caducaEnS < ofertas + eleccion)
             return 'Caduca antes de que acabe el tiempo de elegir.';
     }
+    if (p.adjuntos?.length) {
+        const archivos = problemaConArchivos(p.adjuntos);
+        if (archivos)
+            return archivos;
+    }
     if (p.campana && (p.campana.topePorAgente < 1 || p.campana.topePorAgente > 255)) {
         return 'El tope de una campaña es de 1 a 255 encargos por agente.';
     }
@@ -251,3 +257,69 @@ export function tablonEntregaSignMessage(jobId, resultHash, expira) {
 export function tablonResultadoSignMessage(jobId, expira) {
     return `Panal tablón con reglas · resultado #${jobId.toString()} · ${expira}`;
 }
+/** Su cliente sube un adjunto del encargo, o su agente un archivo de la entrega. */
+export function tablonArchivoSignMessage(jobId, expira) {
+    return `Panal tablón con reglas · archivo #${jobId.toString()} · ${expira}`;
+}
+/*
+ * Archivos en el tablón.
+ *
+ * Los mismos que en un encargo normal: el hash de cada archivo va DENTRO del
+ * texto que se ancla —el encargo, en `[panal-attach/1]`; la entrega, en
+ * `[panal-files/1]`—, así que la cadena cubre los bytes y nadie los cambia
+ * después. Los bytes viajan por el buzón del tablón, que solo los da al cliente
+ * y a su agente.
+ *
+ * Los topes son POR LADO. El buzón guarda 10 archivos y 60 MB por encargo entre
+ * los dos (bot/src/buzon-store.ts); la mitad para los adjuntos del cliente y la
+ * mitad para la entrega, para que adjuntar mucho no deje al agente sin sitio.
+ */
+export const MAX_ARCHIVOS_TABLON = 5;
+export const MAX_BYTES_ARCHIVOS_TABLON = 30 * 1024 * 1024;
+/**
+ * El texto de una entrega del tablón con sus archivos anunciados: nombre,
+ * tamaño, tipo y hash de cada uno, dentro de lo que se ancla. La ruta es
+ * relativa al buzón del tablón (`${buzonUrl}/${tablon}`).
+ *
+ * UNA sola función para todos —SDK, web, app y plantilla— porque este texto se
+ * hashea: dos versiones que difieran en un espacio darían dos hashes, y el
+ * cliente vería una entrega que no cuadra con la anclada.
+ */
+export function entregaConArchivos(jobId, texto, archivos) {
+    const entregados = archivos.map((a) => {
+        const nombre = sanitizeFileName(a.name);
+        return {
+            name: nombre,
+            size: a.bytes.byteLength,
+            hash: keccak256(a.bytes),
+            ...(a.mime ? { mime: a.mime } : {}),
+            path: `/archivo/${jobId.toString()}/${encodeURIComponent(nombre)}?de=entrega`,
+        };
+    });
+    return appendFilesManifest(texto, entregados);
+}
+/** Por qué estos archivos no caben en un lado del encargo, o `null`. */
+export function problemaConArchivos(archivos) {
+    if (archivos.length > MAX_ARCHIVOS_TABLON)
+        return `Como mucho ${MAX_ARCHIVOS_TABLON} archivos.`;
+    const nombres = [];
+    for (const a of archivos) {
+        try {
+            nombres.push(sanitizeFileName(a.name));
+        }
+        catch {
+            return `«${a.name}» no es un nombre de archivo que se pueda usar.`;
+        }
+        if (a.bytes.byteLength === 0)
+            return `«${a.name}» está vacío.`;
+        if (a.bytes.byteLength > MAX_FILE_BYTES)
+            return `«${a.name}» pasa de ${MAX_FILE_BYTES / 1024 / 1024} MB.`;
+    }
+    // Se piden por nombre: dos con el mismo serían uno.
+    if (new Set(nombres).size !== nombres.length)
+        return 'Hay dos archivos con el mismo nombre.';
+    const total = archivos.reduce((n, a) => n + a.bytes.byteLength, 0);
+    if (total > MAX_BYTES_ARCHIVOS_TABLON)
+        return `Entre todos pasan de ${MAX_BYTES_ARCHIVOS_TABLON / 1024 / 1024} MB.`;
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panal/sdk",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "SDK de Panal: contrata agentes de IA autonomos on-chain en Monad",
   "type": "module",
   "license": "MIT",