@superblocksteam/sdk 1.4.1 → 1.5.0

package/src/sdk.ts

@@ -7,18 +7,18 @@ import {
   fetchApi,
   fetchApis,
   fetchApplication,
-  fetchApplicationWithComponents,
+  fetchApplicationBranches,
   fetchApplications,
-  registerComponents,
-  uploadComponents,
+  fetchApplicationWithComponents,
   fetchCurrentUser,
-  ViewMode,
+  pushApi,
+  PushApiWithCommitConfig,
   pushApplication,
   PushApplicationWithCommitConfig,
-  fetchApplicationBranches,
-  PushApiWithCommitConfig,
-  pushApi,
+  registerComponents,
+  uploadComponents,
   validateGitSetup,
+  ViewMode,
 } from "./client";
 
 // Exporting here instead of index.ts because only sdk.ts is exposed outside in package.json
@@ -27,10 +27,16 @@ export * from "./errors";
 export class SuperblocksSdk {
   token = "";
   superblocksBaseUrl = "";
+  cliVersion = "";
 
-  constructor(accessToken: string, superblocksBaseUrl: string) {
+  constructor(
+    accessToken: string,
+    superblocksBaseUrl: string,
+    cliVersion: string
+  ) {
     this.token = accessToken;
     this.superblocksBaseUrl = superblocksBaseUrl;
+    this.cliVersion = cliVersion;
   }
 
   async fetchApplication({
@@ -45,6 +51,7 @@ export class SuperblocksSdk {
     viewMode?: ViewMode;
   }) {
     return fetchApplication({
+      cliVersion: this.cliVersion,
       applicationId,
       branch,
       token: this.token,
@@ -56,6 +63,7 @@ export class SuperblocksSdk {
 
   async fetchApplicationBranches(applicationId: string, headers = {}) {
     return fetchApplicationBranches({
+      cliVersion: this.cliVersion,
       applicationId,
       token: this.token,
       superblocksBaseUrl: this.superblocksBaseUrl,
@@ -75,6 +83,7 @@ export class SuperblocksSdk {
     viewMode?: ViewMode;
   }) {
     return fetchApplicationWithComponents({
+      cliVersion: this.cliVersion,
       applicationId,
       branch,
       token: this.token,
@@ -85,15 +94,31 @@ export class SuperblocksSdk {
   }
 
   async fetchApplications(headers?: Record<string, string>) {
-    return fetchApplications(this.token, this.superblocksBaseUrl, headers);
+    return fetchApplications(
+      this.cliVersion,
+      this.token,
+      this.superblocksBaseUrl,
+      headers
+    );
   }
 
-  async fetchApi(apiId: string, viewMode: ViewMode = "export-live") {
-    return fetchApi(apiId, this.token, this.superblocksBaseUrl, viewMode);
+  async fetchApi(
+    apiId: string,
+    viewMode: ViewMode = "export-live",
+    branch?: string
+  ) {
+    return fetchApi(
+      this.cliVersion,
+      apiId,
+      this.token,
+      this.superblocksBaseUrl,
+      viewMode,
+      branch
+    );
   }
 
   async fetchApis() {
-    return fetchApis(this.token, this.superblocksBaseUrl);
+    return fetchApis(this.cliVersion, this.token, this.superblocksBaseUrl);
   }
 
   async validateGitSetup(
@@ -104,6 +129,7 @@ export class SuperblocksSdk {
     injectedHeaders?: Record<string, string>
   ) {
     return validateGitSetup(
+      this.cliVersion,
       resourceId,
       resourceType,
       event,
@@ -118,9 +144,10 @@ export class SuperblocksSdk {
     applicationId: string,
     componentConfigs: Record<string, any>,
     branch: string | null,
-    injectedHeaders?: Record<string, string>
+    injectedHeaders: Record<string, string>
   ) {
     return registerComponents(
+      this.cliVersion,
       applicationId,
       componentConfigs,
       this.token,
@@ -137,6 +164,7 @@ export class SuperblocksSdk {
     branch: string | null
   ) {
     return uploadComponents({
+      cliVersion: this.cliVersion,
       applicationId,
       componentConfigs,
       files,
@@ -147,7 +175,11 @@ export class SuperblocksSdk {
   }
 
   async fetchCurrentUser() {
-    return fetchCurrentUser(this.token, this.superblocksBaseUrl);
+    return fetchCurrentUser(
+      this.cliVersion,
+      this.token,
+      this.superblocksBaseUrl
+    );
   }
 
   async pushApplication({
@@ -162,6 +194,7 @@ export class SuperblocksSdk {
     headers?: Record<string, string>;
   }) {
     return pushApplication({
+      cliVersion: this.cliVersion,
       applicationId,
       token: this.token,
       superblocksBaseUrl: this.superblocksBaseUrl,
@@ -182,6 +215,7 @@ export class SuperblocksSdk {
     headers?: Record<string, string>;
   }) {
     return pushApi({
+      cliVersion: this.cliVersion,
       apiId,
       apiConfig,
       token: this.token,

package/src/socket/handlers.ts

@@ -0,0 +1,228 @@
+import {
+  ApiToSign,
+  ApiToVerify,
+  AppToSign,
+  AppToVerify,
+  MethodHandlers,
+  RemoteCommitDto,
+  Signature,
+} from "../types";
+import { signResource, verifyResources } from "./signing";
+
+type MethodSchema<Params, Response> = (params: Params) => Promise<Response>;
+
+export interface ClientMethods {
+  v1: {
+    signing: {
+      signApplication: MethodSchema<
+        { branchName: string; toSign: AppToSign },
+        { signature: Signature }
+      >;
+      signApis: MethodSchema<
+        { branchName: string; toSign: ApiToSign[] },
+        { signatures: Signature[] }
+      >;
+      verifyApplication: MethodSchema<
+        { branchName: string; toVerify: AppToVerify },
+        { ok: boolean }
+      >;
+      verifyApi: MethodSchema<
+        { branchName: string; toVerify: ApiToVerify[] },
+        { ok: boolean }
+      >;
+    };
+  };
+}
+
+type ServerMethodSchema<Params, Response> = MethodSchema<
+  Params,
+  ResponseDto<Response>
+>;
+
+// This file contains the definition of the protocol used for communication between the SB server and clients
+
+type ResponseDto<T> = {
+  responseMeta: ResponseMeta;
+  data: T;
+};
+
+export type ResponseMeta = {
+  status: number;
+  success: boolean;
+  error?: APIResponseError;
+};
+
+type APIResponseError = {
+  code: number;
+  message: string;
+};
+
+export interface ServerMethods {
+  v1: {
+    echo: MethodSchema<{ message: string }, { message: string }>;
+    public: {
+      application: {
+        component: {
+          register: ServerMethodSchema<
+            {
+              applicationId: string;
+              branchName: string;
+              cliVersion: string;
+              componentEvent: string;
+              components: Record<string, unknown>;
+            },
+            { success: boolean }
+          >;
+          update: ServerMethodSchema<
+            {
+              applicationId: string;
+              branchName?: string;
+              srcFiles: string[];
+              buildFiles: string[];
+              registeredComponents: Record<string, unknown>;
+              cliVersion: string | undefined;
+              componentBaseUrl: string;
+              signingRequired: boolean;
+            },
+            { success: boolean }
+          >;
+        };
+        pushCommit: ServerMethodSchema<
+          {
+            applicationId: string;
+            branchName: string;
+            commitId: string;
+            commitMessage: string;
+            application: Record<string, unknown>;
+            page: Record<string, unknown>;
+            apis: Record<string, unknown>[];
+          },
+          RemoteCommitDto
+        >;
+      };
+      api: {
+        pushCommit: ServerMethodSchema<
+          {
+            apiId: string;
+            branchName: string;
+            commitId: string;
+            commitMessage: string;
+            apiPb: Record<string, unknown>;
+          },
+          RemoteCommitDto
+        >;
+      };
+    };
+  };
+}
+
+export function createRequestHandlers({
+  agentUrls,
+  token,
+}: {
+  token: string;
+  agentUrls: string[];
+}) {
+  const requestHandlers: MethodHandlers<ClientMethods, ServerMethods, unknown> =
+    {
+      v1: {
+        signing: {
+          signApplication: [
+            async ({
+              branchName,
+              toSign,
+            }: {
+              branchName: string;
+              toSign: AppToSign;
+            }) => {
+              const signature = await signResource({
+                agentUrls,
+                token: token,
+                branchName,
+                resource: {
+                  literal: {
+                    data: toSign.rootHash,
+                  },
+                },
+              });
+              return { signature: signature };
+            },
+          ],
+          signApis: [
+            async ({
+              branchName,
+              toSign,
+            }: {
+              branchName: string;
+              toSign: ApiToSign[];
+            }) => {
+              const signatures: Signature[] = [];
+              for (const { apiPb } of toSign) {
+                const signature = await signResource({
+                  agentUrls,
+                  token: token,
+                  branchName,
+                  resource: { api: apiPb },
+                });
+                signatures.push(signature);
+              }
+              return { signatures };
+            },
+          ],
+          verifyApplication: [
+            async ({
+              branchName,
+              toVerify,
+            }: {
+              branchName: string;
+              toVerify: AppToVerify;
+            }) => {
+              try {
+                await verifyResources({
+                  agentUrls,
+                  token,
+                  branchName,
+                  resources: [
+                    {
+                      literal: {
+                        data: toVerify.rootHash,
+                        signature: toVerify.signature,
+                      },
+                    },
+                  ],
+                });
+                return { ok: true };
+              } catch {
+                return { ok: false };
+              }
+            },
+          ],
+
+          verifyApi: [
+            async ({
+              branchName,
+              toVerify,
+            }: {
+              branchName: string;
+              toVerify: ApiToVerify[];
+            }) => {
+              try {
+                await verifyResources({
+                  agentUrls,
+                  token,
+                  branchName,
+                  resources: toVerify.map(({ apiPb }) => ({
+                    api: apiPb,
+                  })),
+                });
+                return { ok: true };
+              } catch {
+                return { ok: false };
+              }
+            },
+          ],
+        },
+      },
+    };
+  return requestHandlers;
+}

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 ");
+}