@superblocksteam/sdk 1.4.2 → 1.5.0

package/src/socket/index.ts

@@ -0,0 +1,164 @@
+import WebSocket from "isomorphic-ws";
+import {
+  ClientMethods,
+  createRequestHandlers,
+  ServerMethods,
+} from "./handlers";
+import { createISocketClient, ISocket } from "./socket";
+
+export type StdISocketRPCClient = ISocketClient<ServerMethods>;
+
+export async function connectToISocketRPCServer({
+  superblocksBaseUrl,
+  agentUrls,
+  token,
+}: {
+  superblocksBaseUrl: string;
+  agentUrls: string[];
+  token: string;
+}): Promise<StdISocketRPCClient> {
+  const requestHandlers = createRequestHandlers({
+    agentUrls,
+    token,
+  });
+  const authorization = `Bearer ${token}`;
+  const wsUrl = new URL("api/v1/rpc-ws", superblocksBaseUrl);
+  if (wsUrl.protocol === "http:") {
+    wsUrl.protocol = "ws:";
+  } else if (wsUrl.protocol === "https:") {
+    wsUrl.protocol = "wss:";
+  }
+
+  if (wsUrl.host === "localhost:3000") {
+    wsUrl.host = "127.0.0.1:8080";
+  } else if (wsUrl.hostname === "localhost") {
+    wsUrl.hostname = "127.0.0.1";
+  }
+  return await connectISocket<ServerMethods, ClientMethods, unknown>(
+    wsUrl.href,
+    authorization,
+    requestHandlers
+  );
+}
+
+// a subclass of ISocket that sends an auth token on the first request
+// this is useful for client-side sockets that need to authenticate
+// TODO(george): if we start using this for long-lived connections, we should add a way to refresh the token
+class ISocketWithClientAuth<
+  ImplementedMethods,
+  CallableMethods,
+  RequestContext = void
+> extends ISocket<ImplementedMethods, CallableMethods, RequestContext> {
+  private readonly authorization?: string;
+  private hasSentAuth = false;
+
+  constructor(
+    ws: WebSocket,
+    authorization: string | undefined,
+    requestHandlers: MethodHandlers<
+      ImplementedMethods,
+      CallableMethods,
+      RequestContext
+    >
+  ) {
+    super(ws, requestHandlers);
+    this.authorization = authorization;
+  }
+
+  // override `request` from the base class to send `authorization` when appropriate
+  async request<Params, Result>(
+    method: string,
+    params: Params
+  ): Promise<Result> {
+    // only send `authorization` on the first request
+    const authorization = this.hasSentAuth ? undefined : this.authorization;
+    const result = await super.request<Params, Result>(
+      method,
+      params,
+      authorization
+    );
+    this.hasSentAuth = true;
+    return result;
+  }
+}
+
+export async function connectISocket<
+  CallableMethods,
+  ImplementedMethods,
+  RequestContext = never
+>(
+  wsUrl: string,
+  authorization: string | undefined,
+  requestHandlers: MethodHandlers<
+    ImplementedMethods,
+    CallableMethods,
+    RequestContext
+  >
+): Promise<ISocketClient<CallableMethods>> {
+  const ws = await connectWebSocket(wsUrl);
+  const isocket = new ISocketWithClientAuth(ws, authorization, requestHandlers);
+  return createISocketClient(isocket);
+}
+
+export function connectWebSocket(wsUrl: string): Promise<WebSocket> {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(wsUrl);
+
+    ws.addEventListener("open", () => {
+      // Resolve the promise with the WebSocket instance when the connection is open
+      resolve(ws);
+    });
+
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    ws.addEventListener("error", (error: Error) => {
+      // Reject the promise if there's an error
+      reject(error);
+    });
+  });
+}
+
+type MethodHandler<Params, Result, PeerMethods, RequestContext> = (
+  params: Params,
+  peer: ISocketClient<PeerMethods>,
+  ctx: RequestContext
+) => Promise<Result>;
+
+type MiddlewareHandler<Params, PeerMethods, RequestContext> = (
+  params: Params,
+  peerAuthorization: string | undefined,
+  peer: ISocketClient<PeerMethods>,
+  ctx: RequestContext
+) => Promise<void>;
+
+type MethodHandlers<Methods, PeerMethods, RequestContext> = {
+  [Key in keyof Methods]: Methods[Key] extends (
+    params: infer Params
+  ) => Promise<infer Result>
+    ? [
+        ...middlewareHandlers: MiddlewareHandler<
+          Params,
+          PeerMethods,
+          RequestContext
+        >[],
+        handler: MethodHandler<Params, Result, PeerMethods, RequestContext>
+      ]
+    : Methods[Key] extends Record<string, unknown>
+    ? MethodHandlers<Methods[Key], PeerMethods, RequestContext>
+    : never;
+};
+
+type ISocketClientMethodCall<Methods> = {
+  [Key in keyof Methods]: Methods[Key] extends (
+    params: infer P
+  ) => Promise<infer R>
+    ? (params: P) => Promise<R>
+    : Methods[Key] extends Record<string, unknown>
+    ? ISocketClientMethodCall<Methods[Key]>
+    : never;
+};
+
+type ISocketClient<Methods> = {
+  close: () => void;
+  call: ISocketClientMethodCall<Methods>;
+};

package/src/socket/signing.ts

@@ -0,0 +1,113 @@
+import axios, { AxiosRequestConfig, Method } from "axios";
+import {
+  ApiResource,
+  GenericResource,
+  Signature,
+  SignatureResponse,
+} from "../types";
+import { getSanitizedApi } from "../utils";
+
+export async function signResource({
+  token,
+  branchName,
+  resource,
+  agentUrls,
+}: {
+  token: string;
+  branchName: string;
+  resource: ApiResource | GenericResource;
+  agentUrls: string[];
+}): Promise<Signature> {
+  const requestResource: Record<string, any> = {
+    branchName: branchName ?? "main",
+  };
+  if ((resource as ApiResource).api) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    requestResource.api = getSanitizedApi((resource as ApiResource).api);
+  } else {
+    requestResource.literal = (resource as GenericResource).literal;
+  }
+
+  try {
+    const resp = await callAgentFallBack<SignatureResponse>({
+      baseUrls: agentUrls,
+      path: "v1/signature/sign",
+      method: "post",
+      token: token,
+      data: { resource: requestResource },
+    });
+    return resp.signature;
+  } catch (e) {
+    throw new Error("No agents available to sign the resource");
+  }
+}
+
+export async function verifyResources({
+  agentUrls,
+  token,
+  branchName,
+  resources,
+}: {
+  resources: Array<GenericResource | ApiResource>;
+  token: string;
+  branchName: string;
+  agentUrls: string[];
+}): Promise<void> {
+  try {
+    await callAgentFallBack<{ keyId: string }>({
+      baseUrls: agentUrls,
+      path: "v1/signature/verify",
+      method: "post",
+      token: token,
+      data: {
+        resources: resources.map((res) => {
+          if ((res as ApiResource).api) {
+            return {
+              // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+              api: getSanitizedApi((res as ApiResource).api),
+              branchName: branchName ?? "main",
+            };
+          }
+          return {
+            ...res,
+            branchName: branchName ?? "main",
+          };
+        }),
+      },
+    });
+  } catch (e) {
+    throw new Error("No agents available to verify the resource");
+  }
+}
+
+async function callAgentFallBack<T>({
+  baseUrls,
+  path,
+  method,
+  token,
+  data,
+}: {
+  baseUrls: string[];
+  path: string;
+  method: Method;
+  token: string;
+  data: any;
+}): Promise<T> {
+  for (const baseUrl of baseUrls) {
+    try {
+      const url = new URL(path, baseUrl);
+      const config: AxiosRequestConfig = {
+        url: url.toString(),
+        method: method,
+        headers: {
+          Authorization: "Bearer " + token,
+        },
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        data: data,
+      };
+      const resp = await axios<T>(config);
+      return resp.data;
+    } catch (e) {}
+  }
+  throw new Error("Failed to request ");
+}

package/src/socket/socket.ts

@@ -0,0 +1,253 @@
+import WebSocket from "isomorphic-ws";
+import {
+  ISocketClient,
+  MethodHandler,
+  MethodHandlers,
+  MiddlewareHandler,
+} from "../types";
+
+interface SocketRequest<Payload = unknown> {
+  method: string;
+  payload: Payload;
+  id: number;
+  setAuthorization?: string;
+}
+
+interface SocketResponse<Payload = unknown> {
+  id: number;
+  payload: Payload;
+  error: SocketError | null;
+}
+
+interface SocketMessage<RequestPayload = unknown, ResponsePayload = unknown> {
+  request?: SocketRequest<RequestPayload>;
+  response?: SocketResponse<ResponsePayload>;
+}
+
+interface SocketError {
+  message: string;
+  code: number;
+}
+
+export class ISocket<ImplementedMethods, CallableMethods, RequestContext> {
+  private readonly ws: WebSocket;
+  private readonly requestHandlers: MethodHandlers<
+    ImplementedMethods,
+    CallableMethods,
+    RequestContext
+  >;
+  private readonly responseHandler: {
+    [requestId: number]: {
+      resolve: (data: unknown) => void;
+      reject: (error: SocketError) => void;
+    };
+  } = {};
+  private peerAuthorization?: string;
+  private nxtRequestId: number;
+
+  constructor(
+    ws: WebSocket,
+    requestHandlers: MethodHandlers<
+      ImplementedMethods,
+      CallableMethods,
+      RequestContext
+    >
+  ) {
+    this.ws = ws;
+    this.requestHandlers = requestHandlers;
+    this.nxtRequestId = 0;
+
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    this.ws.addEventListener("message", async (event: MessageEvent) => {
+      const eventData: SocketMessage = JSON.parse(event.data.toString());
+      if (eventData.request) {
+        // Split the method string into parts
+        const parts = eventData.request.method.split(".");
+        let handlers = this.requestHandlers;
+        for (const part of parts) {
+          // @ts-ignore
+          handlers = handlers[part];
+          if (!handlers) {
+            return await this.respondError(eventData.request.id, {
+              code: 2,
+              message: `unknown method ${eventData.request.method}`,
+            });
+          }
+        }
+
+        if (!Array.isArray(handlers)) {
+          return await this.respondError(eventData.request.id, {
+            code: 2,
+            message: "unknown method",
+          });
+        }
+        if (eventData.request.setAuthorization) {
+          this.peerAuthorization = eventData.request.setAuthorization;
+        }
+        const middlewareHandlers = handlers.slice(0, -1) as MiddlewareHandler<
+          unknown,
+          CallableMethods,
+          RequestContext
+        >[];
+        const handler = handlers[handlers.length - 1] as MethodHandler<
+          unknown,
+          unknown,
+          CallableMethods,
+          RequestContext
+        >;
+        const reqCtx = {} as RequestContext;
+        let response: unknown;
+        // TODO(george): maybe we should not create a new client for each request
+        const client = createISocketClient(this);
+        try {
+          for (const middlewareHandler of middlewareHandlers) {
+            await middlewareHandler(
+              eventData.request.payload,
+              this.peerAuthorization,
+              client,
+              reqCtx
+            );
+          }
+          response = await handler(eventData.request.payload, client, reqCtx);
+        } catch (error: any) {
+          return await this.respondError(eventData.request.id, {
+            code: 3,
+            message: error.toString(),
+          });
+        }
+        await this.respond(eventData.request.id, response);
+      } else if (eventData.response && eventData.response.id) {
+        if (!this.responseHandler[eventData.response.id]) {
+          return;
+        }
+        if (eventData.response.error) {
+          this.responseHandler[eventData.response.id].reject(
+            eventData.response.error
+          );
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.responseHandler[eventData.response.id].resolve(
+          eventData.response.payload as any
+        );
+        delete this.responseHandler[eventData.response.id];
+      } else {
+        return await this.respondError(-1, {
+          code: 3,
+          message: "unknown request id",
+        });
+      }
+    });
+  }
+
+  public request<Params, Result>(
+    method: string,
+    params: Params,
+    authorization?: string
+  ): Promise<Result> {
+    return new Promise<Result>((resolve, reject) => {
+      const requestId = ++this.nxtRequestId;
+      this.responseHandler[requestId] = {
+        resolve: (result) => resolve(result as Result),
+        reject: (error: SocketError) => reject(error),
+      };
+      const toSend: SocketMessage = {
+        request: {
+          method,
+          payload: params,
+          id: requestId,
+          setAuthorization: authorization,
+        },
+      };
+      this.ws.send(JSON.stringify(toSend));
+    });
+  }
+
+  private async respond<Result>(
+    requestId: number,
+    result: Result
+  ): Promise<void> {
+    const toSend: SocketMessage = {
+      response: {
+        payload: result,
+        id: requestId,
+        error: null,
+      },
+    };
+    return this.ws.send(JSON.stringify(toSend));
+  }
+
+  private async respondError(
+    requestId: number,
+    error: SocketError
+  ): Promise<void> {
+    const toSend: SocketMessage = {
+      response: {
+        payload: null,
+        id: requestId,
+        error: error,
+      },
+    };
+    return this.ws.send(JSON.stringify(toSend));
+  }
+
+  public close(): void {
+    this.ws.close();
+  }
+}
+
+const proxyTarget = Object.freeze(() => {
+  /* return nothing */
+});
+
+function createIsocketProxy<
+  ImplementedMethods,
+  CallableMethods,
+  RequestContext
+>(
+  socket: ISocket<ImplementedMethods, CallableMethods, RequestContext>,
+  // if path is undefined, it means the current object is the root object
+  path: string | undefined
+): unknown {
+  return new Proxy(proxyTarget, {
+    get(_target, prop: string) {
+      const childPath = path ? `${path}.${prop}` : prop;
+      // sometimes, when `createISocketClient` is called from an async function, JS will implicitly call the `then` method on
+      // its return value, because promises can be arbitrarily nested
+      // so return undefined for the `then` method to avoid this
+      if (childPath === "then") {
+        return undefined;
+      }
+      return createIsocketProxy(socket, childPath);
+    },
+
+    apply(_target, _thisArg, args: unknown[]) {
+      if (path === undefined) {
+        throw new Error("The root object is not callable");
+      }
+      if (
+        path.endsWith(".apply") &&
+        args.length === 2 &&
+        Array.isArray(args[1])
+      ) {
+        path = path.slice(0, -".apply".length);
+        args = args[1];
+      }
+      return socket.request(path, args[0]);
+    },
+  });
+}
+
+export function createISocketClient<
+  CallableMethods,
+  ImplementedMethods,
+  RequestContext
+>(
+  socket: ISocket<ImplementedMethods, CallableMethods, RequestContext>
+): ISocketClient<CallableMethods> {
+  return {
+    close: () => socket.close(),
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any,@typescript-eslint/no-unsafe-assignment
+    call: createIsocketProxy(socket, undefined) as any,
+  };
+}

package/src/types/common.ts

@@ -0,0 +1,138 @@
+export interface UserMeDto {
+  user: User;
+  organizations: Organization[];
+  agents: Agent[];
+  flagBootstrap: FlagBootstrap;
+}
+
+export interface FlagBootstrap {
+  "ui.enable-resource-signing"?: boolean;
+}
+
+export type User = {
+  id: string;
+  email: string;
+  currentOrganizationId: string;
+  organizationIds: string[];
+  username: string;
+  name: string;
+  anonymousId: string;
+  isAnonymous: boolean;
+  isAdmin: boolean;
+  metadata: Record<string, unknown>;
+};
+
+export interface Organization {
+  id: string;
+  name: string;
+  displayName: string;
+  agents?: Agent[];
+  apiKey: string;
+  agentType: AgentType;
+  minExternalAgentVersion: string;
+  profiles?: Profile[];
+}
+
+export type Agent = {
+  id: string;
+  key: string;
+  environment: string;
+  status: AgentStatus;
+  version: string;
+  versionExternal: string;
+  url: string;
+  type: AgentType;
+  updated: Date;
+  created: Date;
+  tags: AgentTags;
+  verificationKeyIds?: null | string[];
+  signingKeyId?: null | string;
+};
+
+export enum AgentStatus {
+  ACTIVE = "Active",
+  DISCONNECTED = "Disconnected",
+  BROWSER_UNREACHABLE = "Browser Unreachable",
+  // TODO: remove PENDING_REGISTRATION after the DB migration
+  PENDING_REGISTRATION = "Pending Registration",
+  STALE = "Stale",
+}
+
+export enum AgentType {
+  MULTITENANT = 0,
+  DEDICATED = 1,
+  ONPREMISE = 2,
+}
+
+export type AgentTags = Record<string, string[]>;
+
+export class Profile {
+  id: string;
+  key: string;
+  displayName: string;
+  description: string;
+  type: ProfileType;
+
+  constructor({
+    id,
+    key,
+    displayName,
+    description,
+    type,
+  }: {
+    id: string;
+    key: string;
+    displayName: string;
+    description: string;
+    type: ProfileType;
+  }) {
+    this.id = id;
+    this.key = key;
+    this.displayName = displayName;
+    this.description = description;
+    this.type = type;
+  }
+}
+
+export enum ProfileType {
+  RESERVED = "RESERVED",
+  CUSTOM = "CUSTOM",
+}
+
+export type Api = {
+  metadata: {
+    name: string;
+    id: string;
+    organization: string;
+    timestamps?: {
+      created: string;
+      updated: string;
+      deactivated: boolean;
+    };
+    // These properties are merged in from the v3 api entity
+    creator?: {
+      id: string;
+      name: string;
+    };
+    folder?: string;
+  };
+  blocks?: any[];
+  trigger: any;
+  signature?: Signature;
+};
+
+/** A signature, as produced by the agent. */
+export interface Signature {
+  /** The id of the key used to sign the data. */
+  keyId: string;
+  /** The actual signature, in base64. */
+  data: string;
+}
+
+export interface RemoteCommitDto {
+  commitId: string;
+  remoteCommitId: string;
+  remoteCommitDate: Date;
+  branchName: string;
+  repositoryId: string;
+}

package/src/types/index.ts

@@ -0,0 +1,4 @@
+export * from "./common";
+export * from "./socket";
+export * from "./plugin";
+export * from "./signing";

package/src/types/plugin.ts

@@ -0,0 +1,7 @@
+export const transcribeAudioToTextTranslateToEnglishTruthyValues = [
+  "checked",
+  "true",
+  true,
+];
+
+export const OpenAiPluginId = "openai";