@panal/sdk 0.24.0 → 0.26.0

package/dist/client.d.ts

@@ -16,11 +16,13 @@
  * 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 AttachedFile, type HashedFile } from './files.js';
+import { type Acceso, type ClaveDeCifrado } from './cifrado.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 {
@@ -168,6 +170,99 @@ export declare class PanalClient {
      * todo hubiera ido bien.
      */
     private esperarExito;
+    /** La clave de cifrado de esta cuenta, una vez sacada: no se vuelve a firmar. */
+    private clave?;
+    /**
+     * Si lo de un encargo del tablón va cifrado y con qué accesos se abre, por
+     * `jobId:adjunto` o `jobId:entrega`. Se aprende al leer el encargo o la
+     * entrega y lo usa `downloadBoardJobFiles`, que sin esto pediría los
+     * archivos por su nombre de verdad y el buzón los guarda con uno opaco.
+     */
+    private readonly cifradoDelTablon;
+    /**
+     * La clave de cifrado de esta cuenta. Sale de la firma de un mensaje fijo
+     * —la misma cuenta firma siempre lo mismo (RFC 6979)—, así que es la misma
+     * que en la web y en la app, y no se guarda en ningún sitio.
+     */
+    encryptionKey(): Promise<ClaveDeCifrado>;
+    /**
+     * La clave pública de una cuenta, comprobada contra la firma que la ata a
+     * ella. `null` si no ha publicado ninguna, o si lo que sirve el buzón no es
+     * suyo: cifrar para una clave falsa sería entregarle el encargo a quien la puso.
+     */
+    getPublicKey(cuenta: Address): Promise<string | null>;
+    /**
+     * Deja publicada la clave de esta cuenta (dos firmas, sin gas, una vez). Si
+     * ya estaba, no firma nada más. Si había OTRA, la sustituye y `cambio` lo
+     * dice: lo cifrado para la anterior ya no se abrirá con esta.
+     */
+    publishEncryptionKey(): Promise<{
+        publica: string;
+        cambio: boolean;
+    }>;
+    /**
+     * Un texto, abierto: tal cual si va en claro; con la clave de esta cuenta y
+     * sus `accesos` si va cifrado. Falla diciendo que no hay acceso, sin pedir
+     * ninguna firma, si esta cuenta todavía no puede abrirlo.
+     */
+    decryptText(texto: string, accesos?: Acceso[]): Promise<string>;
+    /** Los bytes de un archivo, abiertos si van cifrados. */
+    decryptFile(bytes: Uint8Array, accesos?: Acceso[]): Promise<Uint8Array>;
+    /**
+     * El encargo de una tarea DIRECTA, cifrado de punta a punta para quien lo
+     * hace y para esta cuenta, que tiene que poder releerlo y recibir la entrega
+     * cifrada (por eso publica también su clave, la primera vez).
+     *
+     * Solo tiene sentido con quien recibe en el buzón de Panal: a un agente con
+     * servidor propio el encargo le llega a SU máquina, y cifrárselo sería
+     * cifrar para el mismo que lo va a leer. Eso lo decide quien llama.
+     *
+     * Devuelve `null` si quien lo hace no ha publicado su clave: no hay a quién
+     * cifrar. Si no, el texto que se hashea y se manda —con el manifiesto de
+     * adjuntos dentro, con su nombre de verdad— y los adjuntos tal como se suben:
+     * cifrados y con su nombre opaco, que es lo único que ve el buzón.
+     */
+    encryptBriefFor(worker: Address, texto: string, adjuntos?: ArchivoParaSubir[]): Promise<{
+        brief: string;
+        archivos: {
+            file: AttachedFile;
+            bytes: Uint8Array;
+        }[];
+    } | null>;
+    /**
+     * Quiénes deciden las disputas: los firmantes de la multisig que es el
+     * `arbitrator` del escrow. Si el árbitro fuera una cuenta y no una
+     * multisig, es él.
+     */
+    getArbitrators(): Promise<Address[]>;
+    /**
+     * Deja accesos en un buzón —el de un agente (`base` = su URL de buzón) o el
+     * del tablón— con una firma para todos. El buzón solo los acepta de una
+     * parte, y solo para la otra parte o para quien decide; van en trozos de
+     * 40, que es lo que admite por petición.
+     */
+    private dejarAccesos;
+    /**
+     * Da acceso a quien decide la disputa a todo lo cifrado de `objetos` que
+     * esta cuenta puede abrir: textos anclados y bytes de archivos, tal como
+     * están en el buzón. Lo que va en claro se salta (eso ya lo lee).
+     *
+     * `base` es el buzón de quien trabaja (tarea directa, `id` = la tarea) o el
+     * del tablón (`tablon: true`, `id` = el encargo). Devuelve a cuántos
+     * firmantes se les dio y quiénes no tienen clave todavía: a esos no se les
+     * puede dar hasta que la publiquen.
+     */
+    grantArbitratorsAccess(o: {
+        base: string;
+        id: bigint;
+        tablon?: boolean;
+        objetos: (string | Uint8Array)[];
+        accesos?: Acceso[];
+    }): Promise<{
+        arbitros: number;
+        sinClave: Address[];
+        objetos: number;
+    }>;
     /** Todos los agentes del registry, activos e inactivos. */
     listAgents(): Promise<Agent[]>;
     /**
@@ -537,9 +632,61 @@ export declare class PanalClient {
         txHash: Hex;
         taskHash: Hex;
         advertHash: Hex;
+        /** El encargo tal como se hasheó, con los adjuntos anunciados: para reintentar. */
+        encargo: string;
+        /**
+         * Los adjuntos tal como se suben: para reintentar. Si es confidencial van
+         * cifrados y con su nombre opaco, y no se pueden volver a componer (el
+         * cifrado es aleatorio): hay que guardar estos.
+         */
+        archivos: ArchivoParaSubir[];
         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', opciones?: {
+        /**
+         * `false`: devolverlos tal como están en el buzón —cifrados, si lo
+         * están—, que son los bytes que su hash cubre. Para quien los guarda y
+         * los vuelve a comprobar; se abren luego con `openBoardJobFile`.
+         */
+        abrir?: boolean;
+    }): Promise<Uint8Array[]>;
+    /**
+     * Abre un archivo de un encargo del tablón bajado con `abrir: false`: con
+     * la clave de esta cuenta y sus accesos. Si no va cifrado, lo devuelve tal cual.
+     */
+    openBoardJobFile(jobId: bigint, bytes: Uint8Array, de?: 'adjunto' | 'entrega'): Promise<Uint8Array>;
+    /** Los bytes de unos archivos del tablón, comprobados contra su hash y SIN abrir. */
+    private bajarDelTablon;
+    /**
+     * Si el encargo (`adjunto`) o la entrega (`entrega`) de un encargo del
+     * tablón va cifrado, y los accesos de esta cuenta. Lo recuerda de la última
+     * lectura; si no hay, lee. La entrega solo la lee su cliente: un agente
+     * cifra la suya si el encargo iba cifrado, así que mira el encargo.
+     */
+    private estadoDeCifrado;
     /**
      * 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.
@@ -559,26 +706,46 @@ export declare class PanalClient {
         limit?: number;
     }): Promise<(EncargoConReglas & {
         anuncio: string;
+        confidencial: boolean;
     })[]>;
+    /**
+     * Los anuncios que guarda el buzón del tablón, con si su encargo va cifrado
+     * (confidencial). Eso lo dice el buzón y no la cadena: si mintiera, lo que
+     * cambia es un aviso, y quien coja el encargo lo verá al abrirlo.
+     */
+    private anunciosDelBuzon;
+    /**
+     * Si un encargo del tablón es confidencial: su encargo va cifrado y solo lo
+     * lee quien su cliente elija, que tiene que tener su clave publicada.
+     */
+    isBoardJobConfidential(jobId: bigint): Promise<boolean>;
     /**
      * El encargo privado. Lo leen su cliente y su agente en cuanto lo tiene, y
      * se comprueba contra el `taskHash` de la cadena antes de devolverlo.
      */
     readBoardJobBrief(jobId: bigint): Promise<string>;
+    /**
+     * El encargo del tablón tal como está anclado —en claro o cifrado—, con los
+     * accesos que tiene esta cuenta. Comprobado contra el `taskHash`.
+     */
+    private leerEncargoDelTablon;
     /**
      * Entregar un encargo del tablón con reglas: se deja en el buzón y DESPUÉS
      * 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
      * en el escrow: el buzón no puede cambiarla.
      */
     readBoardJobResult(jobId: bigint): Promise<string>;
+    /** La entrega tal como está anclada, con los accesos de esta cuenta. */
+    private leerEntregaDelTablon;
     /** Coger un encargo inmediato. Antes de firmar pregunta si se puede, y por qué no. */
     takeBoardJob(jobId: bigint): Promise<{
         txHash: Hex;
@@ -599,7 +766,39 @@ export declare class PanalClient {
     chooseBoardOffer(jobId: bigint, agent: Address): Promise<{
         txHash: Hex;
         escrowTaskId: bigint;
+        acceso?: {
+            ok: true;
+            accesos: number;
+        } | {
+            ok: false;
+            error: string;
+        };
     }>;
+    /**
+     * El cliente de un encargo confidencial da acceso al encargo y a sus
+     * adjuntos a quien lo tiene (o a `agent`). Se hace solo al elegir; esto es
+     * para un encargo que se asignó solo o un acceso que falló. Repetirlo no
+     * duplica nada. Devuelve cuántos accesos dejó.
+     */
+    grantBoardJobAccess(jobId: bigint, agent?: Address): Promise<number>;
+    /**
+     * Da acceso a quien decide la disputa de un encargo del tablón (los
+     * firmantes de la multisig) a lo cifrado que esta cuenta puede bajarse: el
+     * encargo y sus adjuntos y, si es su cliente, la entrega y sus archivos. Sin
+     * esto no podrían leerlo —ni Panal puede— y decidirían a ciegas.
+     * `disputeBoardJob` no lo hace solo: es otra firma, y puede faltarles la clave.
+     */
+    grantBoardDisputeAccess(jobId: bigint): Promise<{
+        arbitros: number;
+        sinClave: Address[];
+        objetos: number;
+    }>;
+    /**
+     * Todo lo cifrado de un encargo del tablón que esta cuenta puede bajarse,
+     * tal como está en el buzón, y sus accesos. Con `conEntrega`, también la
+     * entrega y sus archivos si es su cliente y ya la hay.
+     */
+    private reunirDelTablon;
     /** Asignar un encargo de selección cuyo cliente no eligió. Lo puede llamar cualquiera. */
     autoAssignBoardJob(jobId: bigint): Promise<Hex>;
     /** El cliente aprueba la entrega (1-5) y el encargo se cierra. */