feat: stronger typing for long running operations

src/keri/app/contacting.ts

@@ -1,6 +1,6 @@
 import { SignifyClient } from './clienting.ts';
-import { Operation } from './coring.ts';
 import { components } from '../../types/keria-api-schema.ts';
+import { ChallengeOperation } from '../core/keyState.ts';
 import { Exn } from './exchanging.ts';
 
 export type Contact = components['schemas']['Contact'];
@@ -169,7 +169,7 @@ export class Challenges {
      * @param words List of challenge words to check for
      * @returns A promise to the long running operation
      */
-    async verify(source: string, words: string[]): Promise<Operation<unknown>> {
+    async verify(source: string, words: string[]): Promise<ChallengeOperation> {
         const path = `/challenges_verify/${source}`;
         const method = 'POST';
         const data = {

src/keri/app/coring.ts

@@ -3,6 +3,37 @@ import libsodium from 'libsodium-wrappers-sumo';
 import { Salter } from '../core/salter.ts';
 import { Matter, MtrDex } from '../core/matter.ts';
 import { components } from '../../types/keria-api-schema.ts';
+import {
+    OOBIOperation,
+    QueryOperation,
+    EndRoleOperation,
+    WitnessOperation,
+    DelegationOperation,
+    RegistryOperation,
+    LocSchemeOperation,
+    ChallengeOperation,
+    ExchangeOperation,
+    SubmitOperation,
+    DoneOperation,
+    CredentialOperation,
+    GroupOperation,
+    DelegatorOperation,
+    CompletedOOBIOperation,
+    CompletedQueryOperation,
+    CompletedEndRoleOperation,
+    CompletedWitnessOperation,
+    CompletedDelegationOperation,
+    CompletedRegistryOperation,
+    CompletedLocSchemeOperation,
+    CompletedChallengeOperation,
+    CompletedExchangeOperation,
+    CompletedSubmitOperation,
+    CompletedDoneOperation,
+    CompletedCredentialOperation,
+    CompletedGroupOperation,
+    CompletedDelegatorOperation,
+    CompletedOperation,
+} from '../core/keyState.ts';
 
 type OOBI = components['schemas']['OOBI'];
 type KeyState = components['schemas']['KeyStateRecord'];
@@ -51,9 +82,9 @@ export class Oobis {
      * @async
      * @param {string} oobi The OOBI to be resolver
      * @param {string} [alias] Optional name or alias to link the OOBI resolution to a contact
-     * @returns {Promise<Operation<unknown>>} A promise to the long-running operation
+     * @returns {Promise<OOBIOperation>} A promise to the long-running operation
      */
-    async resolve(oobi: string, alias?: string): Promise<Operation<unknown>> {
+    async resolve(oobi: string, alias?: string): Promise<OOBIOperation> {
         const path = `/oobis`;
         const data: any = {
             url: oobi,
@@ -67,17 +98,21 @@ export class Oobis {
     }
 }
 
-// TODO: the generic will be replaced by specific overrides like IpexOperation
-export type Operation<T = unknown> = Omit<
-    components['schemas']['Operation'],
-    'response' | 'metadata'
-> & {
-    response?: T;
-    metadata?: {
-        depends?: Operation;
-        [property: string]: any;
-    };
-};
+export type Operation =
+    | OOBIOperation
+    | QueryOperation
+    | EndRoleOperation
+    | WitnessOperation
+    | DelegationOperation
+    | RegistryOperation
+    | LocSchemeOperation
+    | ChallengeOperation
+    | ExchangeOperation
+    | SubmitOperation
+    | DoneOperation
+    | CredentialOperation
+    | GroupOperation
+    | DelegatorOperation;
 
 export interface OperationsDeps {
     fetch(
@@ -103,13 +138,44 @@ export class Operations {
         this.client = client;
     }
 
+    private hasDepends(op: Operation): op is (
+        | RegistryOperation
+        | CredentialOperation
+        | DelegatorOperation
+    ) & {
+        metadata: NonNullable<
+            (
+                | RegistryOperation
+                | CredentialOperation
+                | DelegatorOperation
+            )['metadata']
+        >;
+    } {
+        return op.metadata !== undefined && 'depends' in op.metadata;
+    }
+
+    /**
+     * Check if operation failed and throw error with details
+     * @throws {Error} If operation has an error
+     */
+    private throwIfFailed(op: Operation): asserts op is CompletedOperation {
+        if ('error' in op && op.error !== null) {
+            const details = op.error.details
+                ? ` Details: ${JSON.stringify(op.error.details)}`
+                : '';
+            throw new Error(
+                `Operation '${op.name}' failed [Code ${op.error.code}]: ${op.error.message}${details}`
+            );
+        }
+    }
+
     /**
      * Get operation status
      * @async
      * @param {string} name Name of the operation
      * @returns {Promise<Operation>} A promise to the status of the operation
      */
-    async get<T = unknown>(name: string): Promise<Operation<T>> {
+    async get(name: string): Promise<Operation> {
         const path = `/operations/${name}`;
         const data = null;
         const method = 'GET';
@@ -122,7 +188,7 @@ export class Operations {
      * @param {string} type Select operations by type
      * @returns {Promise<Operation[]>} A list of operations
      */
-    async list(type?: string): Promise<Operation<unknown>[]> {
+    async list(type?: string): Promise<Operation[]> {
         const params = new URLSearchParams();
         if (type !== undefined) {
             params.append('type', type);
@@ -148,42 +214,182 @@ export class Operations {
     /**
      * Poll for operation to become completed.
      */
-    async wait<T>(
-        op: Operation<T>,
+    async wait(
+        op: OOBIOperation,
+        options?: {
+            signal?: AbortSignal;
+            minSleep?: number;
+            maxSleep?: number;
+            increaseFactor?: number;
+        }
+    ): Promise<CompletedOOBIOperation>;
+    async wait(
+        op: QueryOperation,
+        options?: {
+            signal?: AbortSignal;
+            minSleep?: number;
+            maxSleep?: number;
+            increaseFactor?: number;
+        }
+    ): Promise<CompletedQueryOperation>;
+    async wait(
+        op: EndRoleOperation,
+        options?: {
+            signal?: AbortSignal;
+            minSleep?: number;
+            maxSleep?: number;
+            increaseFactor?: number;
+        }
+    ): Promise<CompletedEndRoleOperation>;
+    async wait(
+        op: WitnessOperation,
+        options?: {
+            signal?: AbortSignal;
+            minSleep?: number;
+            maxSleep?: number;
+            increaseFactor?: number;
+        }
+    ): Promise<CompletedWitnessOperation>;
+    async wait(
+        op: DelegationOperation,
+        options?: {
+            signal?: AbortSignal;
+            minSleep?: number;
+            maxSleep?: number;
+            increaseFactor?: number;
+        }
+    ): Promise<CompletedDelegationOperation>;
+    async wait(
+        op: RegistryOperation,
+        options?: {
+            signal?: AbortSignal;
+            minSleep?: number;
+            maxSleep?: number;
+            increaseFactor?: number;
+        }
+    ): Promise<CompletedRegistryOperation>;
+    async wait(
+        op: LocSchemeOperation,
+        options?: {
+            signal?: AbortSignal;
+            minSleep?: number;
+            maxSleep?: number;
+            increaseFactor?: number;
+        }
+    ): Promise<CompletedLocSchemeOperation>;
+    async wait(
+        op: ChallengeOperation,
+        options?: {
+            signal?: AbortSignal;
+            minSleep?: number;
+            maxSleep?: number;
+            increaseFactor?: number;
+        }
+    ): Promise<CompletedChallengeOperation>;
+    async wait(
+        op: ExchangeOperation,
+        options?: {
+            signal?: AbortSignal;
+            minSleep?: number;
+            maxSleep?: number;
+            increaseFactor?: number;
+        }
+    ): Promise<CompletedExchangeOperation>;
+    async wait(
+        op: SubmitOperation,
+        options?: {
+            signal?: AbortSignal;
+            minSleep?: number;
+            maxSleep?: number;
+            increaseFactor?: number;
+        }
+    ): Promise<CompletedSubmitOperation>;
+    async wait(
+        op: DoneOperation,
+        options?: {
+            signal?: AbortSignal;
+            minSleep?: number;
+            maxSleep?: number;
+            increaseFactor?: number;
+        }
+    ): Promise<CompletedDoneOperation>;
+    async wait(
+        op: CredentialOperation,
+        options?: {
+            signal?: AbortSignal;
+            minSleep?: number;
+            maxSleep?: number;
+            increaseFactor?: number;
+        }
+    ): Promise<CompletedCredentialOperation>;
+    async wait(
+        op: GroupOperation,
+        options?: {
+            signal?: AbortSignal;
+            minSleep?: number;
+            maxSleep?: number;
+            increaseFactor?: number;
+        }
+    ): Promise<CompletedGroupOperation>;
+    async wait(
+        op: DelegatorOperation,
+        options?: {
+            signal?: AbortSignal;
+            minSleep?: number;
+            maxSleep?: number;
+            increaseFactor?: number;
+        }
+    ): Promise<CompletedDelegatorOperation>;
+    async wait(
+        op: Operation,
+        options?: {
+            signal?: AbortSignal;
+            minSleep?: number;
+            maxSleep?: number;
+            increaseFactor?: number;
+        }
+    ): Promise<CompletedOperation>;
+    async wait(
+        op: Operation,
         options: {
             signal?: AbortSignal;
             minSleep?: number;
             maxSleep?: number;
             increaseFactor?: number;
         } = {}
-    ): Promise<Operation<T>> {
+    ): Promise<CompletedOperation> {
         const minSleep = options.minSleep ?? 10;
         const maxSleep = options.maxSleep ?? 10000;
         const increaseFactor = options.increaseFactor ?? 50;
 
-        if (op.metadata?.depends?.done === false) {
+        if (
+            this.hasDepends(op) &&
+            op.metadata.depends &&
+            !op.metadata.depends.done
+        ) {
             await this.wait(op.metadata.depends, options);
         }
 
         if (op.done === true) {
+            this.throwIfFailed(op);
             return op;
         }
 
         let retries = 0;
-
         while (true) {
             op = await this.get(op.name);
 
+            if (op.done === true) {
+                this.throwIfFailed(op);
+                return op;
+            }
+
             const delay = Math.max(
                 minSleep,
                 Math.min(maxSleep, 2 ** retries * increaseFactor)
             );
             retries++;
 
-            if (op.done === true) {
-                return op;
-            }
-
             await new Promise((resolve) => setTimeout(resolve, delay));
             options.signal?.throwIfAborted();
         }
@@ -265,13 +471,13 @@ export class KeyStates {
      * @param {string} pre Identifier prefix
      * @param {number} [sn] Optional sequence number
      * @param {any} [anchor] Optional anchor
-     * @returns {Promise<Operation<unknown>>} A promise to the long-running operation
+     * @returns {Promise<QueryOperation>} A promise to the long-running operation
      */
     async query(
         pre: string,
         sn?: string,
         anchor?: any
-    ): Promise<Operation<unknown>> {
+    ): Promise<QueryOperation> {
         const path = `/queries`;
         const data: any = {
             pre: pre,