feat: add basic docs (#10)

* feat: add docs for app client * chore: README cleanup * feat: add auth client docs * chore: README cleanup * chore: README cleanup
farcasterxyz · Dec 21, 2023 · b4dd200 · b4dd200
1 parent 2555920
commit b4dd200
Show file tree

Hide file tree

Showing 9 changed files with 526 additions and 23 deletions.
diff --git a/packages/README.md b/packages/README.md
diff --git a/packages/connect/src/actions/app/status.ts b/packages/connect/src/actions/app/status.ts
@@ -10,7 +10,6 @@ export type StatusResponse = AsyncHttpResponse<StatusAPIResponse>;
 interface StatusAPIResponse {
   state: "pending" | "completed";
   nonce: string;
-  connectURI: string;
   message?: string;
   signature?: `0x${string}`;
   fid?: number;

diff --git a/packages/connect/src/actions/app/verifySignInMessage.test.ts b/packages/connect/src/actions/app/verifySignInMessage.test.ts
@@ -25,14 +25,14 @@ describe("verifySignInMessage", () => {
   };
 
   test("verifies sign in message", async () => {
-    const message = authClient.buildSignInMessage({
+    const { message } = authClient.buildSignInMessage({
       ...siweParams,
       address: account.address,
       fid: 1234,
     });
 
     const signature = await account.signMessage({
-      message: message.toMessage(),
+      message,
     });
 
     const errMsg = `Invalid resource: signer ${account.address} does not own fid 1234.`;
@@ -48,14 +48,14 @@ describe("verifySignInMessage", () => {
 
   test("verifies 1271 sign in message", async () => {
     const LGTM = "0xC89858205c6AdDAD842E1F58eD6c42452671885A";
-    const message = authClient.buildSignInMessage({
+    const { message } = authClient.buildSignInMessage({
       ...siweParams,
       address: LGTM,
       fid: 1234,
     });
 
     const signature = await account.signMessage({
-      message: message.toMessage(),
+      message,
     });
 
     const errMsg = `Invalid resource: signer ${LGTM} does not own fid 1234.`;

diff --git a/packages/connect/src/actions/auth/buildSignInMessage.test.ts b/packages/connect/src/actions/auth/buildSignInMessage.test.ts
@@ -8,7 +8,7 @@ describe("buildSignInMessage", () => {
   });
 
   test("builds Siwe message from provided parameters", async () => {
-    const message = client.buildSignInMessage({
+    const { siweMessage, message } = client.buildSignInMessage({
       address: "0x63C378DDC446DFf1d831B9B96F7d338FE6bd4231",
       uri: "https://example.com/login",
       domain: "example.com",
@@ -17,7 +17,7 @@ describe("buildSignInMessage", () => {
       resources: ["https://example.com/resource"],
     });
 
-    expect(message).toMatchObject({
+    expect(siweMessage).toMatchObject({
       address: "0x63C378DDC446DFf1d831B9B96F7d338FE6bd4231",
       statement: "Farcaster Connect",
       chainId: 10,
@@ -27,5 +27,6 @@ describe("buildSignInMessage", () => {
       nonce: "12345678",
       resources: ["farcaster://fid/1", "https://example.com/resource"],
     });
+    expect(message).toBe(siweMessage.toMessage());
   });
 });
diff --git a/packages/connect/src/actions/auth/buildSignInMessage.ts b/packages/connect/src/actions/auth/buildSignInMessage.ts
@@ -3,13 +3,17 @@ import { build, SignInMessageParams } from "../../messages/build";
 import { SiweMessage } from "siwe";
 
 export type BuildSignInMessageArgs = SignInMessageParams;
-export type BuildSignInMessageResponse = SiweMessage;
+export interface BuildSignInMessageResponse {
+  siweMessage: SiweMessage;
+  message: string;
+}
 
 export const buildSignInMessage = (_client: Client, args: BuildSignInMessageArgs): BuildSignInMessageResponse => {
   const result = build(args);
   if (result.isErr()) {
     throw result.error;
   } else {
-    return result.value;
+    const siweMessage = result.value;
+    return { siweMessage, message: siweMessage.toMessage() };
   }
 };
diff --git a/packages/connect/src/actions/auth/parseSignInURI.test.ts b/packages/connect/src/actions/auth/parseSignInURI.test.ts
@@ -15,7 +15,7 @@ describe("parseSignInURI", () => {
     expect(channelToken).toBe("76be6229-bdf7-4ad2-930a-540fb2de1e08");
     expect(params).toStrictEqual({
       domain: "example.com",
-      siweUri: "https://example.com/login",
+      uri: "https://example.com/login",
       nonce: "ESsxs6MaFio7OvqWb",
     });
   });

diff --git a/packages/connect/src/messages/parseSignInURI.test.ts b/packages/connect/src/messages/parseSignInURI.test.ts
@@ -9,7 +9,7 @@ describe("parseSignInUri", () => {
       channelToken: "76be6229-bdf7-4ad2-930a-540fb2de1e08",
       params: {
         domain: "example.com",
-        siweUri: "https://example.com/login",
+        uri: "https://example.com/login",
         nonce: "ESsxs6MaFio7OvqWb",
       },
     });

diff --git a/packages/connect/src/messages/parseSignInURI.ts b/packages/connect/src/messages/parseSignInURI.ts
@@ -4,7 +4,7 @@ import { SignInMessageParams } from "./build";
 
 export interface ParsedSignInURI {
   channelToken: string;
-  params: Partial<SignInMessageParams> & { siweUri?: string };
+  params: Partial<SignInMessageParams>;
 }
 
 export const parseSignInURI = (signInUri: string): ConnectResult<ParsedSignInURI> => {
@@ -23,7 +23,8 @@ export const parseSignInURI = (signInUri: string): ConnectResult<ParsedSignInURI
   if (!params["domain"]) {
     return err(validationFail("No domain provided"));
   }
-  return ok({ channelToken, params });
+  const { siweUri, ...siweParams } = params;
+  return ok({ channelToken, params: { uri: siweUri, ...siweParams } });
 };
 
 const validationFail = (message: string): ConnectError => {

diff --git a/test/client/src/e2e.test.ts b/test/client/src/e2e.test.ts
@@ -67,22 +67,20 @@ describe("clients", () => {
       });
       expect(token).toBe(channelToken);
 
-      const { siweUri, ...siweParams } = params;
-      expect(siweUri).toBe("https://example.com");
-      expect(siweParams.domain).toBe("example.com");
-      expect(siweParams.nonce).toBe("abcd1234");
+      expect(params.uri).toBe("https://example.com");
+      expect(params.domain).toBe("example.com");
+      expect(params.nonce).toBe("abcd1234");
 
       // 3b. Build sign in message
-      const siweMessage = authClient.buildSignInMessage({
-        ...siweParams,
-        uri: siweUri,
+      const { message: messageString } = authClient.buildSignInMessage({
+        ...params,
         address: account.address,
         fid: 1,
       });
 
       // 3c. Collect user signature
       const sig = await account.signMessage({
-        message: siweMessage.toMessage(),
+        message: messageString,
       });
 
       // 3d. Look up userData
@@ -97,7 +95,7 @@ describe("clients", () => {
       // 3e. Send back signed message
       const { response: authResponse } = await authClient.authenticate({
         channelToken,
-        message: siweMessage.toMessage(),
+        message: messageString,
         signature: sig,
         ...userData,
       });
@@ -110,7 +108,7 @@ describe("clients", () => {
       } = await appClient.status({ channelToken });
       expect(completedStatusResponse.status).toBe(200);
       expect(completedState).toBe("completed");
-      expect(message).toBe(siweMessage.toMessage());
+      expect(message).toBe(messageString);
       expect(signature).toBe(sig);
       expect(nonce).toBe(nonce);