Overview

NOTE: As the SDK is still in development, the APIs might change drastically.

Getting started

Google Client API key: You will need a Google OAuth token if you want users to be able to directly query emails from their inbox. Go to Google Cloud's dashboard to enable the Gmail API.

Learn how to create your GOOGLE_CLIENT_ID here.

React Project: The SDK currently only works with reactjs. If you are using nextjs, you might need some workarounds to make sure the page you integrate the SDK runs fully on the client side. Refer to this for reference example.

Wiring it up

Surround a page with the ZkEmailSDKProvider given by the SDK. If you are using nextjs, it is recommended that you only include this in a page that uses the SDK. Else, your entire application will need to be client-side rendered.

import { ZkEmailSDKProvider } from "@zk-email/zk-email-sdk";

function TryPage(props: Props) {
  return (
    <ZkEmailSDKProvider clientId={GOOGLE_CLIENT_ID} zkEmailSDKRegistryUrl='https://registry-dev.zkregex.com'>
        <Page {...props}/>
    </ZkEmailSDKProvider>
  );
};

In your page, the SDK exposes a few hooks to interact with the library.

export function Page(props: Props) {
    const {
        googleAuthToken,
        isGoogleAuthed,
        loggedInGmail,
        googleLogIn,
        googleLogOut,
    } = useGoogleAuth();

    const {
        createInputWorker,
        generateInputFromEmail,
        generateProofRemotely,
        proofStatus,
        inputWorkers
    } = useZkEmailSDK();
}

Hook	Type	Arguments	Description
googleAuthToken	string	-
isGoogleAuthed	boolean	-
loggedInGmail	string	-	User's email
googleLogIn	method	-	Triggers the OAuth page for users to login
googleLogOut	method	-	Deletes the credentials stored in local browser
createInputWorker	method	pattern ID	Creates a worker in the background that processes emails into circuit inputs. This always happens on the client side. It downloads a worker script from the registry and runs it in a sandboxed WebWorker.
generateInputFromEmail	method	pattern ID, raw email	Returns the circuit input generated by processing the email provided
generateProofRemotely	method	pattern ID, circuit input	Uses the circuit input generated and queues a job. Circuit inputs are stored only before/during proof generation. This will automatically poll the server for updates.
proofStatus	{[key:string]: ProofStatus}	-	A map of proof job IDs and the current status + proof outputs.
inputWorkers	{[key: string]: Worker}	-	A map of input worker slugs and their associated web workers.

interface ProofStatus {
    status: string;
    id: string;
    pollUrl: string;
    estimatedTimeLeft: number;
    publicOutput: any;
    proof: any;
}

Example integration

First, create an inputWorker:

createInputWorker("<slug-name>");

Once the input worker is created, it will be populated in the inputWorkers variable. You can monitor this variable. As soon as the inputWorker is created, you can call the generateProofRemotely method:

const [externalInputs, setExternalInputs] = useState<Record<string,string>>({});

// externalInputs - External inputs added when submitting a new pattern at https://registry-dev.zkregex.com/submit
const entryExternalInputs = externalInputs as {name: string, maxLength: number}[] || [];

for (const input of entryExternalInputs) {
    setExternalInputs({
        ...externalInputs,
        [input.name]: "",
    });
}

const input = await generateInputFromEmail(
  "<slug-name>",
  emailFull,
  externalInputs
);

const proofRes = await generateProofRemotely(
  "<slug-name>",
  input
);