@otonoma/paracord-panels-interface 0.17.1-rc.12

package/src/client/managedPncpClient.ts

@@ -0,0 +1,195 @@
+// Conversation manager to make skill requests which expect a direct response able to wait directly on a
+// response.
+
+import { AbstractPncpClient, PncpCallResponse, RegisterObserverCallback, RegisterSkillCallback } from "../";
+import { ObservationCallbackObject, PncpMessageCallbackObject, SkillRequest, PncpRequestCallbackObject, ConversationState, ConversationId, PncpQuestionMessage, PncpMessageKind, PncpAnswerMessage } from "@otonoma/paranet-client";
+import AsyncQueue from "@ai-zen/async-queue";
+
+export class ManagedPncpClient {
+  private convs: Map<number, (msg: PncpMessageCallbackObject) => void>;
+  private convStreams: Map<number, AsyncQueue<PncpMessageCallbackObject>>;
+  private observs: Map<number, (msg: ObservationCallbackObject) => void>;
+  private skills: Map<string, Map<number, (msg: PncpRequestCallbackObject) => void>>;
+  private id: number;
+  client: AbstractPncpClient;
+
+  constructor(base: AbstractPncpClient) {
+    this.convs = new Map();
+    this.convStreams = new Map();
+    this.observs = new Map();
+    this.skills = new Map();
+    this.id = new Date().getTime() + (Math.floor(Math.random() * 10000));
+    let old = base.msgCb;
+    base.msgCb = (msg: PncpMessageCallbackObject) => {
+      if (old)
+        old(msg);
+      if (msg.callback && 'pn/req/id' in msg.callback) {
+        let id = msg.callback['pn/req/id'] as number;
+        if (this.convs.has(id)) {
+          this.convs.get(id)!(msg);
+          this.convs.delete(id);
+        } else if (this.convStreams.has(id)) {
+          let queue = this.convStreams.get(id)!;
+          if (queue.isDone) {
+            this.convs.delete(id);
+          } else {
+            queue.push(msg);
+            if (msg.conversationState == ConversationState.STATE_COMPLETED || msg.conversationState == ConversationState.STATE_ERRORED) {
+              queue.done();
+              this.convs.delete(id);
+            }
+          }
+        }
+      }
+    };
+    let oldObs = base.obsCb;
+    base.obsCb = (msg: ObservationCallbackObject, cb: any) => {
+      if (oldObs)
+        oldObs(msg);
+      console.log("Observer considering callback: ", cb, " on message ", msg);
+      if (cb && 'pn/obs/req/id' in cb) {
+        let id = cb['pn/obs/req/id'] as number;
+        this.observs.get(id)?.(msg);
+      }
+    };
+
+    let oldSk = base.skillCb;
+    base.skillCb = (msg: PncpRequestCallbackObject) => {
+      if (oldSk)
+        oldSk(msg);
+
+      let key = `${msg.body.subject}/${msg.body.action}`;
+      let inner = this.skills.get(key);
+      if (inner) {
+        for (let cb of inner.values()) {
+          cb(msg);
+        }
+      }
+    };
+    this.client = base;
+  }
+
+  // A simple send request which expects _one_ response message.
+  // To make a call which can expect multiple responses, use `createConversation`.
+  public async sendRequest(req: SkillRequest): Promise<ConversationResponse> {
+    let id = this.id++;
+    if (!req.callback) {
+      req.callback = {};
+    }
+
+    req.callback['pn/req/id'] = id;
+    let promise = new Promise<PncpMessageCallbackObject>((res) => {
+      this.convs.set(id, (pncp) => res(pncp));
+    });
+    let reply = await this.client.pncpRequest(req);
+    return new Promise(async (res) => {
+      let pncp = await promise;
+      res({ reply, pncp });
+    });
+  }
+
+  public async createConversation(req: SkillRequest): Promise<ConversationHandler> {
+    let id = this.id++;
+    if (!req.callback) {
+      req.callback = {};
+    }
+
+    req.callback['pn/req/id'] = id;
+
+    let queue: AsyncQueue<PncpMessageCallbackObject> = new AsyncQueue();
+
+    this.convStreams.set(id, queue);
+    let reply = await this.client.pncpRequest(req);
+    return new ConversationHandler(this, queue, reply);
+  }
+
+  public async createObserver(obs: RegisterObserverCallback, cb: (msg: ObservationCallbackObject) => void): Promise<ObserverHandle> {
+    let id = this.id++;
+    if (!obs.callback) {
+      obs.callback = {};
+    }
+    obs.callback['pn/obs/req/id'] = id;
+    this.observs.set(id, cb);
+    // NOTE: This can be clever enough to avoid duplicating these callbacks, but the paracord side can manage
+    // that too, so this should be OK.
+    // TODO: Does this return something useful?
+    let { args: { key } } = await this.client.registerObserverCallback(obs);
+    return new ObserverHandle(this, id, key);
+  }
+
+  public async deleteObserver(id: number, key: string) {
+    this.observs.delete(id);
+    await this.client.deleteObserver(key);
+  }
+
+  public async createSkillCallback(sk: RegisterSkillCallback, cb: (msg: PncpRequestCallbackObject) => void): Promise<number> {
+    let key = `${sk.subject}/${sk.action}`;
+    if (!this.skills.has(key)) {
+      await this.client.registerSkillCallback(sk);
+      this.skills.set(key, new Map());
+    }
+
+    let inner = this.skills.get(key)!;
+    let id = this.id++;
+    inner.set(id, cb);
+    return id;
+  }
+}
+
+export interface ConversationResponse {
+  reply: PncpCallResponse;
+  pncp: PncpMessageCallbackObject;
+}
+
+export class ConversationHandler {
+  private queue: AsyncGenerator<PncpMessageCallbackObject>;
+  private id: ConversationId;
+  private client: ManagedPncpClient;
+
+  constructor(client: ManagedPncpClient, queue: AsyncQueue<PncpMessageCallbackObject>, reply: PncpCallResponse) {
+    this.queue = queue[Symbol.asyncIterator]();
+    // TODO: Throw an error here if this is empty.
+    this.id = reply.conversationId!;
+    this.client = client;
+  }
+
+  public async next(): Promise<PncpMessageCallbackObject | null> {
+    return (await this.queue.next()).value;
+  }
+
+  public async sendQuestion(req: PncpQuestionMessage): Promise<PncpCallResponse> {
+    return await this.client.client.pncpMessage({
+      id: this.id,
+      body: {
+        type: PncpMessageKind.PNCP_QUESTION,
+        value: req,
+      },
+    });
+  }
+
+  public async sendAnswer(req: PncpAnswerMessage): Promise<PncpCallResponse> {
+    return await this.client.client.pncpMessage({
+      id: this.id,
+      body: {
+        type: PncpMessageKind.PNCP_ANSWER,
+        value: req,
+      }
+    });
+  }
+}
+
+export class ObserverHandle {
+  private id: number;
+  private key: string;
+  private client: ManagedPncpClient;
+
+  constructor(client: ManagedPncpClient, id: number, key: string) {
+    this.client = client;
+    this.id = id;
+    this.key = key;
+  }
+
+  public async close() {
+    await this.client.deleteObserver(this.id, this.key);
+  }
+}

package/src/client/paracordClient.ts

@@ -0,0 +1,149 @@
+// Client for panels to connect to paracord and send requests.
+
+import {
+  DocumentArgs,
+  LoginCredentials,
+  ObservationCallbackObject,
+  PncpMessageCallbackObject,
+  PncpMessageObject,
+  PncpRequestCallbackObject,
+  SkillRequest,
+} from "@otonoma/paranet-client";
+import { Channel } from "../channel";
+import {
+  PanelConnect,
+  PanelMethodCall,
+  PARACORD_PANEL_REVISION,
+} from "../interface";
+import {
+  PncpMessageResponse,
+  MethodCall,
+  RegisterSkillCallback,
+  PncpCallResponse,
+  RegisterObserverCallback,
+  GraphqlCallArgs,
+  GraphqlCallResponse,
+  UploadDocumentArgs,
+  UploadDocumentResponse,
+  FetchDocumentResponse,
+  RegisterObserverResponse,
+} from "../interface/methods";
+import { AbstractPncpClient, PncpClientInit } from "../";
+
+export class ParacordClient extends AbstractPncpClient {
+  channel: Channel;
+  skillCb?: (msg: PncpRequestCallbackObject) => void;
+  msgCb?: (msg: PncpMessageCallbackObject) => void;
+  obsCb?: (msg: ObservationCallbackObject, callback?: any) => void;
+  constructor(init?: PncpClientInit) {
+    super(init);
+    // Provided by Paracord.
+    const panelId = window.name;
+    // TODO (JAB): All of the message handling requests should be abstracted in a way that can be generalized
+    // to run in non-panel specific environments. This will make it easier to develop new panels as totally
+    // independent apps instead of requiring the panel embedding. This should both enable quicker/easier
+    // development but also greater portability of the panel code.
+    const message: PanelConnect = {
+      apiRevision: PARACORD_PANEL_REVISION,
+      panelId,
+      type: "panelConnect",
+    };
+    const msgChan = new MessageChannel();
+    // TODO: Implement proper callback here.
+    const channel = new Channel(panelId, msgChan.port1, (msg) => {
+      console.log("Got callback:", msg);
+      switch (msg.body.type) {
+        case "pncpSkillCb":
+          this.skillCb?.(msg.body.body);
+          break;
+        case "pncpMessageCb":
+          this.msgCb?.(msg.body.body);
+          break;
+        case "pncpObservationCb":
+          this.obsCb?.(msg.body.body, msg.body.callback);
+          break;
+      }
+    });
+    this.channel = channel;
+    // Call the background.
+    console.log("Posting channel");
+    top?.postMessage(message, "*", [msgChan.port2]);
+  }
+
+  async issueCall(call: MethodCall): Promise<any> {
+    const body: PanelMethodCall = {
+      type: "call",
+      body: call,
+    };
+    const response = await this.channel.asyncSend(body);
+    if (response.type == "callReturn") {
+      return response.body;
+    } else if (response.type == "paracordError") {
+      throw Error(response.error);
+    } else {
+      throw Error("Incorrect response type.");
+    }
+  }
+
+
+  public async login(_creds: LoginCredentials) { }
+
+  public async pncpRequest(req: SkillRequest): Promise<PncpCallResponse> {
+    return await this.issueCall({ method: "pncpRequest", args: req });
+  }
+
+  public async pncpResponse(
+    req: PncpMessageResponse
+  ): Promise<PncpCallResponse> {
+    return await this.issueCall({ method: "pncpResponse", args: req });
+  }
+
+  public async pncpMessage(
+    req: PncpMessageObject
+  ): Promise<PncpCallResponse> {
+    return await this.issueCall({ method: "pncpMessage", args: req });
+  }
+
+  // Registers the callback with paracord.
+  public async registerSkillCallback(req: RegisterSkillCallback) {
+    return await this.issueCall({ method: "registerSkillCallback", args: req });
+  }
+
+  public async registerObserverCallback(req: RegisterObserverCallback): Promise<RegisterObserverResponse> {
+    return await this.issueCall({
+      method: "registerObserverCallback",
+      args: req,
+    });
+  }
+
+  public async deleteObserver(key: string) {
+    await this.issueCall({ method: "unregisterObserverCallback", args: { key } })
+  }
+
+  public async uploadDocument(args: UploadDocumentArgs): Promise<UploadDocumentResponse> {
+    return await this.issueCall({
+      method: "uploadDocumentCall",
+      args,
+    })
+  }
+
+  public async fetchDocument(args: DocumentArgs): Promise<FetchDocumentResponse> {
+    return await this.issueCall({
+      method: "fetchDocumentCall",
+      args,
+    })
+  }
+
+  public async graphqlCall(args: GraphqlCallArgs): Promise<GraphqlCallResponse> {
+    return await this.issueCall({
+      method: "graphqlCall",
+      args,
+    });
+  }
+}
+
+export interface ParacordClientInit {
+  skill?: (msg: PncpRequestCallbackObject) => void;
+  msg?: (msg: PncpMessageCallbackObject) => void;
+  obs?: (msg: ObservationCallbackObject, callback?: any) => void;
+}

package/src/client/pncpClient.ts

@@ -0,0 +1,304 @@
+// TODO: A lot of this code is copied from the pncpRpcClient found in the main paracord source code.
+// As such, we should refactor that to make use of this code instead. We should likely move this into a more abstract location and not be
+// part of the "panels" library, but something else instead. All of this is totally generic, and it could
+// just live in the paranet-client repo instead, but then we would just need to implement it in the panels
+// library specifically (which already depends on the paranet-client repo, so that would be OK).
+import { DocumentArgs, LoginCredentials, ObservationCallback, ObservationCallbackObject, ObservationInit, ObservationMessageType, ObservationStartPoint, ParanetObserverListener, ParanetServiceClient, PncpCallback, PncpCallbackObject, PncpClient, PncpListener, PncpMessageCallbackObject, PncpMessageKind, PncpMessageObject, PncpRequestCallbackObject, simplifyObservationCallback, simplifyPncpCallback, SkillRequest, Timestamp, TokenResponse } from "@otonoma/paranet-client";
+import { AbstractPncpClient, PncpClientInit } from ".";
+import { FetchDocumentResponse, GraphqlCallArgs, GraphqlCallResponse, PncpCallResponse, PncpMessageResponse, RegisterObserverCallback, RegisterObserverResponse, RegisterSkillCallback, UploadDocumentArgs, UploadDocumentResponse } from "../interface";
+
+export type ConnectionState =
+  | "connected"
+  | "disconnected"
+  | "pending"
+  | "unauthenticated"
+  | "failed";
+
+interface CreateObserver {
+  body: ObservationInit;
+  offset?: number;
+}
+
+export class PncpRpcClient extends AbstractPncpClient {
+  // TODO: We need a service client too for graphql calls.
+  private client: PncpClient;
+  private svcClient: ParanetServiceClient;
+  private listener: PncpListener;
+  private observerState: Map<string, ObserverState>;
+
+  actorId: string;
+  actorVersion: string;
+
+  // Maps `name -> ${subject}/${action} -> ObserverState` style key to an observer set.
+  connectionState: ConnectionState;
+
+  constructor(init: PncpRpcClientInit) {
+    super(init.init);
+    this.connectionState = "disconnected";
+    this.client = new PncpClient({
+      endpoint: init.broker,
+      actorId: init.actorId,
+      // TODO: We need to simplify this process of determining the version of client actors.
+      actorVersion: init.actorVersion,
+      token: init.tokens?.access_token,
+      refreshToken: init.tokens?.refresh_token,
+    });
+
+    this.actorId = init.actorId;
+    this.actorVersion = init.actorVersion;
+
+    this.svcClient = new ParanetServiceClient({
+      actorId: init.actorId,
+      endpoint: init.service,
+    });
+
+    this.client.setTokenCb((token, refresh) => {
+      this.svcClient.setTokens(token, refresh);
+    });
+
+    if (init.tokens) {
+      this.svcClient.setTokens(init.tokens.access_token, init.tokens.refresh_token);
+    }
+    // TODO: Manage connection state, same as PncpRpcClient.
+    const listener = this.client
+      .pncpListener()
+      .onstart(() => {
+        this.connectionState = "connected";
+        // TODO: Trigger a callback here.
+        // useConnectionStore
+        //   .getState()
+        //   .setConnectionState(this.connectionState);
+        // resolve();
+      })
+      .ondisconnect(() => {
+        this.connectionState = "disconnected";
+      })
+      .onreconnect(() => {
+        this.connectionState = "connected";
+      })
+      .onmessage((msg: PncpCallback) => {
+        const simplified = simplifyPncpCallback(msg);
+        switch (simplified.type) {
+          case "skill":
+            {
+              this.skillCb?.(simplified);
+            }
+            break;
+          case "message":
+            {
+              this.msgCb?.(simplified);
+            }
+            break;
+        }
+      })
+      .onerror((err, isFatal) => {
+        // this.error = decodeURIComponent(err);
+        this.connectionState = isFatal ? "unauthenticated" : "failed";
+        // reject(this.error);
+      })
+      .autoReconnect(true);
+
+    this.listener = listener;
+    this.observerState = new Map();
+  }
+
+  public async login(creds: LoginCredentials) {
+    let tokens = await this.client.login(creds);
+    this.svcClient.setTokens(tokens.access_token, tokens.refresh_token);
+  }
+
+  public async pncpRequest(req: SkillRequest): Promise<PncpCallResponse> {
+    let res = await this.client.pncpRequest(req);
+
+    const date =
+      res.timeCreated && Timestamp.toDate(res.timeCreated);
+    return {
+      type: "response",
+      messageId: res.messageId,
+      conversationId: res.id,
+      actorId: res.matchedId?.id,
+      actorVersion: res.matchedId?.version,
+      date,
+    };
+  }
+
+  public async pncpResponse(
+    req: PncpMessageResponse
+  ): Promise<PncpCallResponse> {
+    let response = await this.client.pncpMessage({
+      conversation: req.conversation,
+      message: {
+        type: PncpMessageKind.PNCP_RESPONSE,
+        value: {
+          data: req.data,
+        }
+      },
+    });
+
+    const date = response.timeCreated && Timestamp.toDate(response.timeCreated);
+    const messageId = response.messageId;
+    const entityId = response.matchedId;
+    const actorId = entityId?.id;
+    const actorVersion = entityId?.version;
+
+    return { type: "response", date, messageId, actorId, actorVersion };
+  }
+
+  public async pncpMessage(data: PncpMessageObject): Promise<PncpCallResponse> {
+
+    const response = await this.client.pncpMessageObject(data);
+
+    const date = response.timeCreated && Timestamp.toDate(response.timeCreated);
+    const messageId = response.messageId;
+    const entityId = response.matchedId;
+    const actorId = entityId?.id;
+    const actorVersion = entityId?.version;
+
+    return { type: "response", date, messageId, actorId, actorVersion };
+  }
+
+  public async registerSkillCallback(_req: RegisterSkillCallback) {
+    // Nothing to do. We could have the paranet only send skill requests to certain clients,
+    // like the way observers work now - probably a useful feature. But for now, nothing to do here.
+  }
+
+  public async registerObserverCallback(req: RegisterObserverCallback): Promise<RegisterObserverResponse> {
+    if (!this.obsCb) {
+      throw new Error("Set an observer callback first");
+    }
+    const state = this.createOrGetObserverStream({
+      body: {
+        subject: req.subject,
+        action: req.action,
+        conversationId: req.conversationId,
+        filters: req.filters !== undefined ? req.filters : [{ kind: ObservationMessageType.OBS_MESSAGE_TYPE_SKILL }],
+      },
+      offset: req.offset,
+    });
+    console.log(state);
+    state.observer
+      .onstart(() => {
+        console.log("Started observer stream", req);
+      })
+      .ondisconnect(() => {
+        console.log("Observer disconnected");
+      })
+      .onerror((e) => {
+        console.log("Error from observer:", e);
+      })
+      .onmessage((msg: ObservationCallback) => {
+        const simplified = simplifyObservationCallback(msg);
+        this.obsCb?.(simplified, req.callback);
+      })
+      .autoReconnect(true)
+      .connect();
+    return {
+      type: "registerObserverCallback",
+      args: {
+        key: state.key
+      }
+    };
+  }
+
+  private createOrGetObserverStream({
+    body,
+    offset,
+  }: CreateObserver): ObserverState {
+    if (!body.subject || !body.action) {
+      // TODO: Throw an error.
+    }
+    const key = JSON.stringify({ body, offset })
+      .split("")
+      .sort()
+      .join("");
+
+    let state = this.observerState.get(key);
+    if (state != null) {
+      return state;
+    }
+    // NOTE (JAB, 2025-11-03): We will need to consider if we should allow panels to specify the start point, or just compute
+    // it ourselves. For now, probably better to restrict it.
+    const startPoint = offset
+      ? ObservationStartPoint.OBS_START_OFFSET
+      : body.conversationId
+        ? ObservationStartPoint.OBS_START_BEGINNING
+        : ObservationStartPoint.OBS_START_HEAD;
+    const listener = this.client.observerListener({
+      author: {
+        id: this.actorId,
+        version: this.actorVersion,
+      },
+      body,
+      startPoint,
+      seqOffset: offset ? BigInt(offset) : undefined,
+      // TODO (JAB, 2025-11-04): There may be scenarios where we want to track paracord observers,
+      // but currently this is only used in panels and we never want those to be tracked.
+      untracked: true,
+    });
+    // TODO: Setup the callback information correctly.
+    const newState: ObserverState = {
+      key,
+      observer: listener,
+    };
+
+    this.observerState.set(key, newState);
+    return newState;
+  }
+
+  public async deleteObserver(key: string): Promise<void> {
+    console.log("Removing observer ", key);
+    const state = this.observerState.get(key);
+    if (state) {
+      state.observer.disconnect();
+      this.observerState.delete(key);
+    }
+  }
+
+  public async uploadDocument(args: UploadDocumentArgs): Promise<UploadDocumentResponse> {
+    let response = await this.svcClient.documentUpload(args.body, args.args)
+    return {
+      type: "uploadDocument",
+      body: response,
+    };
+  }
+
+  public async fetchDocument(args: DocumentArgs): Promise<FetchDocumentResponse> {
+    let stream;
+    let error;
+    try {
+      let response = await this.svcClient.documentFetch(args);
+      stream = response.body!;
+    } catch (e) {
+      error = e;
+    }
+    return {
+      type: "fetchDocument",
+      error,
+      stream,
+    };
+  }
+
+  public async graphqlCall(args: GraphqlCallArgs): Promise<GraphqlCallResponse> {
+    let response = await this.svcClient.graphql(args.query, args.variables);
+    return {
+      type: "graphqlCall",
+      data: response.data,
+      error: response.errors,
+    };
+  }
+}
+
+interface ObserverState {
+  observer: ParanetObserverListener;
+  // Used to construct a key for a new observer listener.
+  key: string;
+}
+
+export interface PncpRpcClientInit {
+  init?: PncpClientInit,
+  actorId: string,
+  actorVersion: string,
+  broker: string,
+  service: string,
+  tokens?: TokenResponse,
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./interface";
+export * from "./client";