feat(connect): add basic docs

mrcnk · mrcnk · commit ce7391077ecb · 2024-09-15T20:03:56.000+02:00
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -12,4 +12,4 @@ jobs:
       - run: bun i --no-save
       - run: bun run build
       - run: bun run test
-      - run: bunx pkg-pr-new publish './packages/klesia-sdk' './packages/accounts'
+      - run: bunx pkg-pr-new publish './packages/klesia-sdk' './packages/accounts' './packages/connect'
diff --git a/apps/docs/package.json b/apps/docs/package.json
@@ -18,6 +18,7 @@
 	},
 	"devDependencies": {
 		"@mina-js/klesia-sdk": "workspace:*",
+		"@mina-js/connect": "workspace:*",
 		"daisyui": "^4.12.10"
 	}
 }
diff --git a/apps/docs/src/pages/accounts/getting-started.mdx b/apps/docs/src/pages/accounts/getting-started.mdx
@@ -12,6 +12,16 @@ MinaJS Accounts shares an API similar to [Viem](https://viem.sh/).
 $ npm install @mina-js/accounts
 ```
 
+### Nightly builds
+
+```sh
+$ npm install https://pkg.pr.new/palladians/mina-js/@mina-js/accounts@main
+```
+
+:::warning
+For now there are only [nightly builds](/getting-started#nightly-builds) available. The stable version will be released soon™️.
+:::
+
 ## Utilities
 
 ### generateMnemonic
diff --git a/apps/docs/src/pages/connect/getting-started.mdx b/apps/docs/src/pages/connect/getting-started.mdx
@@ -1 +1,31 @@
 # Getting Started [Start with MinaJS Connect.]
+
+## Installation
+
+```sh
+$ npm install @mina-js/connect
+```
+
+### Nightly builds
+
+```sh
+$ npm install https://pkg.pr.new/palladians/mina-js/@mina-js/connect@main
+```
+
+:::warning
+For now there are only [nightly builds](/getting-started#nightly-builds) available. The stable version will be released soon™️.
+:::
+
+## Find Mina wallets
+
+To discover injected wallet providers, we've developed a Provider Discovery reactive store utility. [Check out the usage](/connect/provider-discovery).
+
+## Window Polyfill
+
+For your convenient TypeScript development, we've created a window polyfill. This will make sure you have an autocompletion for MinaJS compliant providers.
+
+```ts
+import '@mina-js/connect/window'
+
+const account = await window.mina.request({ method: 'mina_accounts' })
+```
diff --git a/apps/docs/src/pages/connect/provider-discovery.mdx b/apps/docs/src/pages/connect/provider-discovery.mdx
@@ -0,0 +1,56 @@
+# Provider Discovery [Discover injected wallet providers with ease.]
+
+For your convenience, MinaJS Connect provides a simple way to discover all Mina's injected wallet providers. This is done by an API similar to [Wevm's MIPD](https://github.com/wevm/mipd).
+
+## Vanilla TypeScript
+
+```ts twoslash
+import { createStore, type MinaProviderDetail } from '@mina-js/connect'
+
+const store = createStore()
+
+// Reactively, you can use MinaProviderDetail to type the array, but it fails in docs ffs.
+const providersReactively = []
+const unsubscribe = store.subscribe((provider) => providersReactively.push(provider))
+
+// Imperatively
+const providersImperatively = store.getProviders()
+```
+
+## React
+
+```tsx twoslash
+import { useSyncExternalStore } from 'react'
+import { createStore } from '@mina-js/connect'
+
+const store = createStore()
+
+function Example() {
+  const providers = useSyncExternalStore(store.subscribe, store.getProviders)
+}
+```
+
+## Svelte
+
+```svelte twoslash
+<script lang="ts">
+  import { readable } from 'svelte/store'
+  import { createStore } from '@mina-js/connect'
+
+  const store = createStore()
+  const providers = readable(store.getProviders(), store.subscribe)
+</script>
+```
+
+## Vue
+
+```vue twoslash
+<script setup lang="ts">
+  import { reactive } from 'vue'
+  import { createStore } from '@mina-js/connect'
+
+  const store = createStore()
+  const state = reactive({ providers: store.getProviders() })
+  store.subscribe(providers => (state.providers = providers))
+</script>
+```
diff --git a/apps/docs/src/pages/getting-started.mdx b/apps/docs/src/pages/getting-started.mdx
@@ -75,3 +75,9 @@ The libraries are available on npm. You can install them using npm, yarn, pnpm,
 - [MinaJS Connect](/connect)
 - [MinaJS Accounts](/accounts)
 - [Klesia SDK](/klesia/sdk)
+
+## Nightly builds
+
+We have nightly builds available for the SDK. You can find the latest nightly versions of our packages on:
+
+https://nightly.akryum.dev/palladians/mina-js
diff --git a/apps/docs/src/pages/klesia/sdk.mdx b/apps/docs/src/pages/klesia/sdk.mdx
@@ -8,8 +8,14 @@ Klesia has a TypeScript SDK to interact with the JSON-RPC API. The SDK provides
 $ npm install @mina-js/klesia-sdk
 ```
 
+### Nightly builds
+
+```sh
+$ npm install https://pkg.pr.new/palladians/mina-js/@mina-js/klesia-sdk@main
+```
+
 :::warning
-For now there are only [nightly builds](/klesia/sdk#nightly-builds) available. The stable version will be released soon™️.
+For now there are only [nightly builds](/getting-started#nightly-builds) available. The stable version will be released soon™️.
 :::
 
 ## Client Options
@@ -34,9 +40,3 @@ const { result } = await client.request<'mina_getTransactionCount'>({
 ## Methods
 
 Refer to the [RPC Methods](/klesia/rpc#rpc-methods) page for a complete list of methods available on Klesia.
-
-## Nightly Builds
-
-We have nightly builds available for the SDK. You can find the latest nightly versions of our packages on:
-
-https://nightly.akryum.dev/palladians/mina-js
diff --git a/apps/docs/vocs.config.ts b/apps/docs/vocs.config.ts
@@ -85,6 +85,7 @@ export default defineConfig({
 			items: [
 				{ text: "Introduction", link: "/connect" },
 				{ text: "Getting Started", link: "/connect/getting-started" },
+				{ text: "Provider Discovery", link: "/connect/provider-discovery" },
 			],
 		},
 		{
diff --git a/bun.lockb b/bun.lockb
diff --git a/packages/connect/package.json b/packages/connect/package.json
@@ -4,10 +4,15 @@
 	"module": "dist/index.js",
 	"types": "dist/index.d.ts",
 	"exports": {
+		"./window": {
+			"types": "./dist/window.d.ts",
+			"default": "./dist/window.js",
+			"import": "./dist/window.mjs"
+		},
 		".": {
 			"types": "./dist/index.d.ts",
-			"default": "./dist/index.cjs",
-			"import": "./dist/index.js"
+			"default": "./dist/index.js",
+			"import": "./dist/index.mjs"
 		}
 	},
 	"scripts": {
@@ -17,6 +22,7 @@
 	},
 	"dependencies": {
 		"@mina-js/providers": "workspace:*",
+		"ts-pattern": "^5.3.1",
 		"zod": "3.23.8"
 	},
 	"peerDependencies": {
diff --git a/packages/connect/src/__mocks__/provider.ts b/packages/connect/src/__mocks__/provider.ts
@@ -10,7 +10,7 @@ export const mockedProvider: MinaProviderDetail = {
 	},
 	provider: {
 		request: mock(),
-		addListener: mock(),
+		on: mock(),
 		removeListener: mock(),
 	},
 };
diff --git a/packages/connect/src/__snapshots__/store.spec.ts.snap b/packages/connect/src/__snapshots__/store.spec.ts.snap
@@ -0,0 +1,13 @@
+// Bun Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`should initialize the store 1`] = `
+{
+  "_listeners": [Function: _listeners],
+  "clear": [Function: clear],
+  "destroy": [Function: destroy],
+  "findProvider": [Function: findProvider],
+  "getProviders": [Function: getProviders],
+  "reset": [Function: reset],
+  "subscribe": [Function: subscribe],
+}
+`;
diff --git a/packages/connect/src/events.spec.ts b/packages/connect/src/events.spec.ts
@@ -5,7 +5,7 @@ import { announceProvider, requestProviders } from "./events";
 
 type Resolver = (value: unknown) => void;
 
-it("announcec Mina Provider with window event", async () => {
+it("announces Mina Provider with window event", async () => {
 	const listener =
 		(resolve: Resolver) =>
 		({ detail }: MinaAnnounceProviderEvent) => {
diff --git a/packages/connect/src/events.ts b/packages/connect/src/events.ts
@@ -43,9 +43,10 @@ export function requestProviders(
 	if (typeof window === "undefined") return;
 	const handler = (event: MinaAnnounceProviderEvent) => listener(event.detail);
 
-	window.addEventListener("mina:announceProvider", handler);
+	window.addEventListener("mina:announceProvider", handler as never);
 
 	window.dispatchEvent(new CustomEvent("mina:requestProvider"));
 
-	return () => window.removeEventListener("mina:announceProvider", handler);
+	return () =>
+		window.removeEventListener("mina:announceProvider", handler as never);
 }
diff --git a/packages/connect/src/global-polyfill.ts b/packages/connect/src/global-polyfill.ts
@@ -0,0 +1,15 @@
+import type {
+	MinaAnnounceProviderEvent,
+	MinaProviderClient,
+	MinaRequestProviderEvent,
+} from "@mina-js/providers";
+
+declare global {
+	interface WindowEventMap {
+		"mina:announceProvider": MinaAnnounceProviderEvent;
+		"mina:requestProvider": MinaRequestProviderEvent;
+	}
+	interface Window {
+		mina?: MinaProviderClient | undefined;
+	}
+}
diff --git a/packages/connect/src/index.ts b/packages/connect/src/index.ts
@@ -1,18 +1,3 @@
-import type {
-	MinaAnnounceProviderEvent,
-	MinaProviderClient,
-	MinaRequestProviderEvent,
-} from "@mina-js/providers";
-
-declare global {
-	interface WindowEventMap {
-		"mina:announceProvider": MinaAnnounceProviderEvent;
-		"mina:requestProvider": MinaRequestProviderEvent;
-	}
-	interface Window {
-		mina?: MinaProviderClient | undefined;
-	}
-}
-
 export * from "./store";
 export * from "./events";
+export type { MinaProviderDetail } from "@mina-js/providers";
diff --git a/packages/connect/src/store.spec.ts b/packages/connect/src/store.spec.ts
@@ -0,0 +1,38 @@
+import { expect, it, mock } from "bun:test";
+import { mockedProvider } from "./__mocks__/provider";
+import { announceProvider } from "./events";
+import { createStore } from "./store";
+
+it("should initialize the store", () => {
+	const store = createStore();
+	expect(store).toMatchSnapshot();
+});
+
+it("should update providers", () => {
+	const store = createStore();
+	const listener = mock();
+	store.subscribe(listener);
+	announceProvider(mockedProvider);
+	const provider = store.getProviders()[0];
+	expect(listener).toHaveBeenCalled();
+	expect(provider).toEqual(mockedProvider);
+});
+
+it("should unsubscribe from store", () => {
+	const store = createStore();
+	const listener = mock();
+	const unsub = store.subscribe(listener);
+	unsub();
+	announceProvider(mockedProvider);
+	expect(listener).not.toHaveBeenCalled();
+});
+
+it("should clear providers list", () => {
+	const store = createStore();
+	const listener = mock();
+	store.subscribe(listener);
+	announceProvider(mockedProvider);
+	store.clear();
+	const providers = store.getProviders();
+	expect(providers.length).toEqual(0);
+});
diff --git a/packages/connect/src/unito.ts b/packages/connect/src/unito.ts
@@ -0,0 +1,16 @@
+import type { MinaProviderDetail } from "@mina-js/providers";
+import { match } from "ts-pattern";
+
+export const unito = (provider: MinaProviderDetail) => {
+	return match(provider)
+		.with({ info: { slug: "auro" } }, (provider) => {
+			return {
+				...provider,
+				provider: {
+					...provider.provider,
+					request: null,
+				},
+			};
+		})
+		.otherwise((provider) => provider);
+};
diff --git a/packages/connect/src/window.ts b/packages/connect/src/window.ts
@@ -0,0 +1 @@
+import "./global-polyfill";
diff --git a/packages/connect/tsup.config.ts b/packages/connect/tsup.config.ts
@@ -1,3 +1,7 @@
+import { defineConfig } from "tsup";
 import sharedConfig from "../shared/tsup.config";
 
-export default sharedConfig;
+export default defineConfig({
+	...sharedConfig,
+	entry: ["./src/index.ts", "./src/window.ts"],
+});
diff --git a/packages/providers/src/types.ts b/packages/providers/src/types.ts
diff --git a/packages/providers/src/validation.ts b/packages/providers/src/validation.ts
diff --git a/packages/shared/src/validation.ts b/packages/shared/src/validation.ts

Original file line number	Diff line number	Diff line change
`@@ -18,6 +18,7 @@`
`18`	`18`	`},`
`19`	`19`	`"devDependencies": {`
`20`	`20`	`"@mina-js/klesia-sdk": "workspace:*",`
	`21`	`+ "@mina-js/connect": "workspace:*",`
`21`	`22`	`"daisyui": "^4.12.10"`
`22`	`23`	`}`
`23`	`24`	`}`
Original file line number	Diff line number	Diff line change
`@@ -85,6 +85,7 @@ export default defineConfig({`
`85`	`85`	`items: [`
`86`	`86`	`{ text: "Introduction", link: "/connect" },`
`87`	`87`	`{ text: "Getting Started", link: "/connect/getting-started" },`
	`88`	`+ { text: "Provider Discovery", link: "/connect/provider-discovery" },`
`88`	`89`	`],`
`89`	`90`	`},`
`90`	`91`	`{`