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

Author: Sotatek-Patrick-Vu

src/keri/app/contacting.ts

@@ -183,15 +183,15 @@ 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;
+        return await res.json() 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,9 @@ 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,