feat: agenting.py type hints and OpenAPI specs #377

src/keri/app/contacting.ts

@@ -183,15 +183,23 @@ export class Challenges {
      * Mark challenge response as signed and accepted
      * @param source Prefix of the identifier that was challenged
      * @param said qb64 AID of exn message representing the signed response
-     * @returns {Promise<Response>} A promise to the result
+     * @returns {Promise<Operation<any>>} A promise to the result
      */
-    async responded(source: string, said: string): Promise<Response> {
+    async responded(source: string, said: string): Promise<Operation<any>> {
         const path = `/challenges_verify/${source}`;
         const method = 'PUT';
         const data = {
             said: said,
         };
         const res = await this.client.fetch(path, method, data);
-        return res;
+        // Check for empty response
+        if (res.status === 204 || res.headers.get('content-length') === '0') {
+            return {} as Operation<any>;
+        }
+        const text = await res.text();
+        if (!text) {
+            return {} as Operation<any>;
+        }
+        return JSON.parse(text) as Operation<any>;
     }
 }

src/keri/app/coring.ts

@@ -5,6 +5,9 @@ import { Matter, MtrDex } from '../core/matter.ts';
 import { components } from '../../types/keria-api-schema.ts';
 
 type OOBI = components['schemas']['OOBI'];
+type KeyState = components['schemas']['KeyStateRecord'];
+type KeyEventRecord = components['schemas']['KeyEventRecord'];
+type AgentConfig = components['schemas']['AgentConfig'];
 
 export function randomPasscode(): string {
     const raw = libsodium.randombytes_buf(16);
@@ -48,9 +51,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<any>} A promise to the long-running operation
+     * @returns {Promise<Operation<any>>} A promise to the long-running operation
      */
-    async resolve(oobi: string, alias?: string): Promise<any> {
+    async resolve(oobi: string, alias?: string): Promise<Operation<any>> {
         const path = `/oobis`;
         const data: any = {
             url: oobi,
@@ -85,10 +88,6 @@ export interface OperationsDeps {
     ): Promise<Response>;
 }
 
-export interface AgentConfig {
-    iurls?: string[];
-}
-
 /**
  * Operations
  * @remarks
@@ -208,9 +207,9 @@ export class KeyEvents {
      * Retrieve key events for an identifier
      * @async
      * @param {string} pre Identifier prefix
-     * @returns {Promise<any>} A promise to the key events
+     * @returns {Promise<KeyEventRecord[]>} A promise to the key events
      */
-    async get(pre: string): Promise<any> {
+    async get(pre: string): Promise<KeyEventRecord[]> {
         const path = `/events?pre=${pre}`;
         const data = null;
         const method = 'GET';
@@ -236,9 +235,9 @@ export class KeyStates {
      * Retriene the key state for an identifier
      * @async
      * @param {string} pre Identifier prefix
-     * @returns {Promise<any>} A promise to the key states
+     * @returns {Promise<KeyState[]>} A promise to the key states
      */
-    async get(pre: string): Promise<any> {
+    async get(pre: string): Promise<KeyState[]> {
         const path = `/states?pre=${pre}`;
         const data = null;
         const method = 'GET';
@@ -252,7 +251,7 @@ export class KeyStates {
      * @param {Array<string>} pres List of identifier prefixes
      * @returns {Promise<any>} A promise to the key states
      */
-    async list(pres: string[]): Promise<any> {
+    async list(pres: string[]): Promise<KeyState[]> {
         const path = `/states?${pres.map((pre) => `pre=${pre}`).join('&')}`;
         const data = null;
         const method = 'GET';
@@ -266,9 +265,13 @@ export class KeyStates {
      * @param {string} pre Identifier prefix
      * @param {number} [sn] Optional sequence number
      * @param {any} [anchor] Optional anchor
-     * @returns {Promise<any>} A promise to the long-running operation
+     * @returns {Promise<Operation<any>>} A promise to the long-running operation
      */
-    async query(pre: string, sn?: string, anchor?: any): Promise<any> {
+    async query(
+        pre: string,
+        sn?: string,
+        anchor?: any
+    ): Promise<Operation<any>> {
         const path = `/queries`;
         const data: any = {
             pre: pre,

src/keri/core/keeping.ts

@@ -181,57 +181,82 @@ export class IdentifierManagerFactory {
         let kargs: any;
 
         if (Algos.salty in aid) {
-            return new SaltyIdentifierManager(
-                this.salter,
-                aid.salty.pidx,
-                aid.salty.kidx,
-                aid.salty.tier,
-                aid.salty.transferable,
-                aid.salty.stem,
-                undefined,
-                undefined,
-                aid.salty.icodes,
-                undefined,
-                undefined,
-                aid.salty.ncodes,
-                aid.salty.dcode,
-                undefined,
-                aid.salty.sxlt
-            );
+            algo = Algos.salty;
+            kargs = aid.salty;
         } else if (Algos.randy in aid) {
-            return new RandyIdentifierManager(
-                this.salter,
-                undefined,
-                undefined,
-                undefined,
-                new Prefixer({ qb64: aid['prefix'] }).transferable,
-                undefined,
-                undefined,
-                [],
-                undefined,
-                aid.randy.prxs,
-                aid.randy.nxts
-            );
+            algo = Algos.randy;
+            kargs = aid.randy;
         } else if (Algos.group in aid) {
-            return new GroupIdentifierManager(
-                this,
-                aid.group.mhab,
-                undefined,
-                undefined,
-                aid.group.keys,
-                aid.group.ndigs
-            );
+            algo = Algos.group;
+            kargs = aid.group;
         } else if (Algos.extern in aid) {
-            const typ = aid.extern.extern_type;
-            if (typ in this.modules) {
-                const mod = new this.modules[typ](aid.extern.pidx, aid.extern);
-                return mod;
-            } else {
-                throw new Error(`unsupported external module type ${typ}`);
-            }
+            algo = Algos.extern;
+            kargs = aid.extern;
         } else {
             throw new Error('No algo specified');
         }
+
+        if (!kargs) {
+            throw new Error('No kargs found in HabState');
+        }
+        switch (algo) {
+            case Algos.salty:
+                kargs = kargs as SaltyKeyState;
+                return new SaltyIdentifierManager(
+                    this.salter,
+                    kargs.pidx,
+                    kargs.kidx,
+                    kargs.tier,
+                    kargs.transferable,
+                    kargs.stem,
+                    undefined,
+                    undefined,
+                    kargs.icodes,
+                    undefined,
+                    undefined,
+                    kargs.ncodes,
+                    kargs.dcode,
+                    undefined,
+                    kargs.sxlt
+                );
+            case Algos.randy:
+                kargs = kargs as RandyKeyState;
+                return new RandyIdentifierManager(
+                    this.salter,
+                    undefined,
+                    undefined,
+                    undefined,
+                    new Prefixer({ qb64: aid['prefix'] }).transferable,
+                    undefined,
+                    undefined,
+                    [],
+                    undefined,
+                    kargs.prxs,
+                    kargs.nxts
+                );
+            case Algos.group:
+                kargs = kargs as GroupKeyState;
+                return new GroupIdentifierManager(
+                    this,
+                    kargs.mhab,
+                    undefined,
+                    undefined,
+                    kargs.keys,
+                    kargs.ndigs
+                );
+            case Algos.extern: {
+                kargs = kargs as ExternState;
+                const typ = kargs.extern_type;
+                if (typ in this.modules) {
+                    const mod = new this.modules[typ](kargs.pidx, kargs);
+                    return mod;
+                } else {
+                    throw new Error(`unsupported external module type ${typ}`);
+                }
+            }
+            default:
+                throw new Error('Algo not allowed yet');
+        }
     }
 }
 

src/keri/core/keyState.ts

@@ -33,4 +33,15 @@ export type ExternState = components['schemas']['ExternState'];
 /**
  * Defining properties of an identifier habitat, know as a Hab in KERIpy.
  */
-export type HabState = components['schemas']['Identifier'];
+// export type HabState = components['schemas']['Identifier'];
+
+export type HabStateBase = components['schemas']['HabState'];
+export type SaltyHabState = HabStateBase & SaltyKeyState;
+export type RandyHabState = HabStateBase & RandyKeyState;
+export type GroupHabState = HabStateBase & GroupKeyState;
+export type ExternHabState = HabStateBase & ExternState;
+export type HabState =
+    | SaltyHabState
+    | RandyHabState
+    | GroupHabState
+    | ExternHabState;

src/keri/core/salter.ts

@@ -4,7 +4,6 @@ import { Matter, MtrDex } from './matter.ts';
 import { EmptyMaterialError } from './kering.ts';
 import libsodium from 'libsodium-wrappers-sumo';
 import { Tier } from '../../types/keria-api-schema.ts';
-
 export { Tier } from '../../types/keria-api-schema.ts';
 
 interface SalterArgs {