Skip to content

Commit

Permalink
docs: document chrono-sdk
Browse files Browse the repository at this point in the history
  • Loading branch information
moreal committed Jun 12, 2024
1 parent e4fdfc7 commit c176745
Showing 5 changed files with 127 additions and 0 deletions.
51 changes: 51 additions & 0 deletions packages/chrono-sdk/src/chrono-wallet.ts
Original file line number Diff line number Diff line change
@@ -6,17 +6,34 @@ import { encodeUnsignedTx, type UnsignedTx } from "@planetarium/tx";
import { EventType, EventHandler, Network } from "./event.js";
import type { PolymorphicAction } from "@planetarium/lib9c";

/**
* Wrapper class for APIs that communicate with the Chrono browser extension.
*/
export class ChronoWallet {
constructor(private readonly handler: WindowMessageHandler) {}

/**
* Subscribe an event with a handler for the event.
* @param event A event to subscribe.
* @param handler A function to handle notified event.
*/
subscribe<T extends EventType>(event: EventType, handler: EventHandler<T>): void {
this.handler.subscribe(event, handler);
}

/**
* Unsubscribe registered event handler.
* @param event An event to unsubscribe.
* @param handler An event handler registered by @see subscribe.
*/
unsubscribe<T extends EventType>(event: EventType, handler: EventHandler<T>): void {
this.handler.unsubscribe(event, handler);
}

/**
* Get selected network in Chrono browser extension.
* @returns A promise that resolves selected network object.
*/
getCurrentNetwork(): Promise<Network> {
return new Promise((resolve, reject) => {
this.handler.send(
@@ -26,6 +43,11 @@ export class ChronoWallet {
});
}

/**
* Switch network in a programmatic way.
* @param networkId A network id of the network to switch.
* @returns A promise.
*/
switchNetwork(networkId: string): Promise<void> {
return new Promise((resolve, reject) => {
this.handler.send(
@@ -35,6 +57,10 @@ export class ChronoWallet {
});
}

/**
* Request to connect accounts to current site.
* @returns A promise that resolves connected accounts' addreses.
*/
connect(): Promise<string[]> {
return new Promise((resolve, reject) => {
this.handler.send(
@@ -44,6 +70,10 @@ export class ChronoWallet {
});
}

/**
* Test this site is connected to Chrono browser extension.
* @returns A promise that resolves a boolean value indicating whether the site is connected.
*/
isConnected(): Promise<boolean> {
return new Promise((resolve, reject) => {
this.handler.send(
@@ -53,6 +83,12 @@ export class ChronoWallet {
});
}

/**
* Sign an unsigned transaction built with selected network and the given `action`, with `signer`s private key.
* @param signer The address to sign. The address must be connected by `connect` process.
* @param action An action used to build unsigned transaction.
* @returns A promise that resolves Buffer instance containing the serialized result of the signed transaction.
*/
sign(signer: Address, action: PolymorphicAction): Promise<Buffer> {
return new Promise((resolve, reject) => {
this.handler.send(
@@ -62,6 +98,12 @@ export class ChronoWallet {
});
}

/**
* Sign the given unsigned transaction with `signer`s private key.
* @param signer The address to sign. The address must be connected by `connect` process.
* @param unsignedTx An unsigned transaction object to sign.
* @returns A promise that resolves Buffer instance containing the serialized result of the signed transaction.
*/
signTx(signer: Address, unsignedTx: UnsignedTx): Promise<Buffer> {
return new Promise((resolve, reject) => {
this.handler.send(
@@ -71,6 +113,10 @@ export class ChronoWallet {
});
}

/**
* Get connected accounts' addresses.
* @returns A promise that resolves connected accounts' addresses.
*/
listAccounts(): Promise<{
address: Address,
}[]> {
@@ -90,6 +136,11 @@ export class ChronoWallet {
});
}

/**
* Get a `PublicKey` instance corresponding to the given `address`.
* @param address An address of the account to get public key.
* @returns A promise that resolves a `PublicKey` instance.
*/
getPublicKey(address: Address): Promise<PublicKey> {
return new Promise((resolve, reject) => {
this.handler.send(
29 changes: 29 additions & 0 deletions packages/chrono-sdk/src/hooks/useAccounts.ts
Original file line number Diff line number Diff line change
@@ -10,6 +10,35 @@ type UseAccountsReturnType = ReturnType<typeof useQuery<{
isConnected: false,
}>>;

/**
* A hook to get accounts from Chrono browser extension with @tanstack/react-query.
* @example Show accounts
* ```tsx
* import { useAccounts } from '@planetarium/chrono-sdk/hooks';
*
* function App() {
* const { isLoading, isSuccess, data, error } = useAccounts();
*
* if (isLoading) {
* return <p>Loading accounts...</p>
* }
*
* if (!isSuccess) {
* return <p>Failed to get accounts: {error}</p>
* }
*
* const { accounts, isConnected } = data;
*
* if (!isConnected) {
* // Show connect button.
* }
*
* return (<div>
* {accounts.map(x => <p key={x.toString()}>{x.toString()}</p>)}
* </div>)
* }
* ```
*/
export function useAccounts(): UseAccountsReturnType {
const sdk = getChronoSdk();

13 changes: 13 additions & 0 deletions packages/chrono-sdk/src/hooks/useConnect.ts
Original file line number Diff line number Diff line change
@@ -9,6 +9,19 @@ type UseConnectReturnType = Omit<UseConnectMutationReturnType, "mutate" | "mutat
connectAsync: UseConnectMutationReturnType["mutateAsync"],
};

/**
* A hook to `connect` to Chrono browser extension with @tanstack/react-query.
* @example Show 'Connect' button
* ```tsx
* import { useConnect } from '@planetarium/chrono-sdk/hooks';
*
* function App() {
* const { connectAsync, isPending } = useConnect();
*
* return <button onClick={() => connectAsync()} disabled={isPending}>Connect</button>
* }
* ```
*/
export function useConnect(): UseConnectReturnType {
const queryClient = useQueryClient();
const { mutate, mutateAsync, ...result } = useMutation({
26 changes: 26 additions & 0 deletions packages/chrono-sdk/src/hooks/useNetwork.ts
Original file line number Diff line number Diff line change
@@ -10,6 +10,32 @@ type UseNetworkReturnType = ReturnType<typeof useQuery<{
isConnected: true,
}>>;

/**
* A hook to get current network from Chrono browser extension with @tanstack/react-query.
* @example Show current network
* ```tsx
* import { useNetwork } from '@planetarium/chrono-sdk/hooks';
*
* function App() {
* const { isLoading, isSuccess, data } = useNetwork();
*
* if (isLoading) {
* return <p>Loading network...</p>
* }
*
* if (!isSuccess) {
* return <p>Failed to fetch network.</p>
* }
*
* const { network, isConnected } = data;
* if (!isConnected) {
* return <p>Not Connected.</p>
* }
*
* return <p>{network}</p>
* }
* ```
*/
export function useNetwork(): UseNetworkReturnType {
const sdk = getChronoSdk();

8 changes: 8 additions & 0 deletions packages/chrono-sdk/src/index.ts
Original file line number Diff line number Diff line change
@@ -1,12 +1,20 @@
import { ChronoWallet } from "./chrono-wallet.js";
import { WindowMessageHandler } from "./handler.js";

/**
* Inject ChronoWallet on `window` global variable.
* Expect to be used by Chrono content-scripts.
*/
export function setupChronoSdk() {
const handler = new WindowMessageHandler(window);
const chronoWallet = new ChronoWallet(handler);
(window as any).chronoWallet = chronoWallet;
}

/**
* Get ChronoWallet injected by Chrono content-scripts.
* @returns The injected ChronoWallet instance.
*/
export function getChronoSdk(): ChronoWallet | undefined {
return (window as any).chronoWallet;
}

0 comments on commit c176745

Please sign in to comment.