Update documentation and examples

README.md

@@ -58,4 +58,4 @@ pnpm watch
 
 To see the apps in action, run either `client-web` or `client-nodejs`. Then run `test-app` and open `test-app` at [http://localhost:3200](http://localhost:3200).
 
-By default it will connect to `client-web` on `http://localhost:5173`. By clicking the lightning icon in the top-right of the screen, you can configure it to connect to another client. `client-nodejs` runs at `http://localhost:3050` - remember to select "websocket" rather than "iframe" when using `client-nodejs`.
+By default it will connect to `client-web` on `http://localhost:5173`. By clicking the lightning icon in the top-right of the screen, you can configure it to connect to another client. `client-nodejs` runs at `http://localhost:3050` - remember to select "websocket" rather than "iframe" when using `client-nodejs`.

examples/test-app/package.json

@@ -12,7 +12,7 @@
   "dependencies": {
     "@parcnet-js/app-connector": "workspace:*",
     "@parcnet-js/podspec": "workspace:*",
-    "@pcd/pod": "0.1.6",
+    "@pcd/pod": "0.1.7",
     "json-bigint": "^1.0.0",
     "lodash": "^4.17.21",
     "react": "^18.2.0",

examples/test-app/src/apis/GPC.tsx

@@ -9,32 +9,36 @@ import { useParcnetClient } from "../hooks/useParcnetClient";
 const request: PodspecProofRequest = {
   pods: {
     pod1: {
-      entries: {
-        wis: {
-          type: "int",
-          inRange: { min: BigInt(5), max: BigInt(1000) },
-          isRevealed: true
+      pod: {
+        entries: {
+          wis: {
+            type: "int",
+            inRange: { min: BigInt(5), max: BigInt(1000) },
+            isRevealed: true
+          },
+          str: { type: "int", inRange: { min: BigInt(5), max: BigInt(1000) } }
         },
-        str: { type: "int", inRange: { min: BigInt(5), max: BigInt(1000) } }
-      },
-      tuples: [
-        {
-          entries: ["wis", "str"],
-          isNotMemberOf: [
-            [
-              { type: "int", value: BigInt(100) },
-              { type: "int", value: BigInt(500) }
+        tuples: [
+          {
+            entries: ["wis", "str"],
+            isNotMemberOf: [
+              [
+                { type: "int", value: BigInt(100) },
+                { type: "int", value: BigInt(500) }
+              ]
             ]
-          ]
-        }
-      ]
+          }
+        ]
+      }
     },
     pod2: {
-      entries: {
-        test: {
-          type: "string",
-          isMemberOf: [{ type: "string", value: "secret" }],
-          isRevealed: true
+      pod: {
+        entries: {
+          test: {
+            type: "string",
+            isMemberOf: [{ type: "string", value: "secret" }],
+            isRevealed: true
+          }
         }
       }
     }

examples/test-app/src/apis/PODSection.tsx

@@ -464,7 +464,10 @@ function DeletePOD({ z }: { z: ParcnetAPI }): ReactNode {
 
 function SubscribeToPODs({ z }: { z: ParcnetAPI }): ReactNode {
   const [pods, setPODs] = useState<POD[]>([]);
-  const [subscription, setSubscription] = useState<Subscription | null>(null);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const [subscription, setSubscription] = useState<Subscription<any> | null>(
+    null
+  );
 
   return (
     <div>

packages/app-connector/README.md

@@ -0,0 +1,108 @@
+# PARCNET App Connector
+
+The app connector is for connecting your app to PARCNET.
+
+## Getting started
+
+Install the package:
+
+```
+npm install @parcnet-js/app-connector
+```
+
+Then connect to a PARCNET client:
+
+```ts
+import { connect } from "@parcnet-js/app-connector";
+
+// Ensure this HTML element exists:
+const element = document.getElementById("app-connector");
+// The URL to the PARCNET client, e.g. Zupass
+const clientUrl = "http://localhost:5173";
+
+// Returns an API object that you can use to invoke actions
+// See api_wrapper.ts for details
+const api = await connect({ name: "My App Name", permissions: []}, element, clientUrl);
+```
+
+This will give you an API object, which can be used to invoke various APIs.
+
+## APIs
+
+### Identity
+
+#### identity.getSemaphoreV3Commitment();
+```ts
+await api.identity.getSemaphoreV3Commitment();
+```
+
+This returns a `bigint` representing the Semaphore v3 commitment.
+
+#### identity.getSemaphoreV4Commitment();
+```ts
+await api.identity.getSemaphoreV4Commitment();
+```
+
+This returns a `bigint` representing the Semaphore v4 commitment.
+
+#### identity.getSemaphoreV4PublicKey();
+```ts
+await api.identity.getSemaphoreV4PublicKey();
+```
+
+This returns a `string` representing the Semaphore v4 public key.
+
+### POD
+
+#### pod.sign
+```ts
+const pod: POD = await api.pod.sign({ type: "string", value: "entry value" });
+```
+
+This will request the signature of a POD with the entries given. An exception may be thrown if the POD is invalid, or if permission is refused for the signing of the POD. Otherwise, the signed POD is returned.
+
+#### pod.insert
+```ts
+await api.pod.insert(pod);
+```
+
+This inserts a POD into the user's POD collection for permanent storage.
+
+#### pod.delete
+```ts
+await api.pod.delete(pod_signature);
+```
+
+This deletes a POD from the user's POD collection, as identified by the POD's signature, which can be retrieved from the `signature` property on a POD.
+
+#### pod.query
+```ts
+await api.pod.query({
+  entries: {
+    str: { type: "int", inRange: { min: 10n, max: 100n }},
+    wis: { type: "int", inRange: { min: 5n, max: 100n }}
+  }
+});
+```
+
+This queries the user's POD collection for matching PODs. For details of the possible query types, see the `@parcnet-js/podspec` package.
+
+### GPC
+
+#### gpc.prove
+```ts
+await api.gpc.prove({
+  pods: {
+    podName: {
+      pod: {
+        entries: {
+          str: { type: "int", inRange: { min: 10n, max: 100n }},
+          wis: { type: "int", inRange: { min: 5n, max: 100n }}
+        }
+      }
+    }
+  }
+})
+```
+
+This requests that the user make a GPC proof about a POD in their collection which matches the criteria specified above. For more examples of the available criteria, see the `@parcnet-js/podspec` library.

packages/app-connector/src/api_wrapper.ts

@@ -19,12 +19,16 @@ import type { ParcnetRPCConnector } from "./rpc_client.js";
  * It also allows the caller to run the query immediately, which is useful on
  * first creating the subscription, before any updates are available.
  */
-export class Subscription {
+export class Subscription<E extends p.EntriesSchema> {
   #emitter: EventEmitter;
-  #query: p.PodSpec;
+  #query: p.PodSpec<E>;
   #api: ParcnetPODWrapper;
 
-  constructor(query: p.PodSpec, emitter: EventEmitter, api: ParcnetPODWrapper) {
+  constructor(
+    query: p.PodSpec<E>,
+    emitter: EventEmitter,
+    api: ParcnetPODWrapper
+  ) {
     this.#emitter = emitter;
     this.#query = query;
     this.#api = api;
@@ -61,12 +65,14 @@ class ParcnetPODWrapper {
     });
   }
 
-  async query(query: p.PodSpec): Promise<POD[]> {
+  async query<E extends p.EntriesSchema>(query: p.PodSpec<E>): Promise<POD[]> {
     const pods = await this.#api.pod.query(query.schema);
     return pods.map((pod) => POD.deserialize(pod));
   }
 
-  async subscribe(query: p.PodSpec): Promise<Subscription> {
+  async subscribe<E extends p.EntriesSchema>(
+    query: p.PodSpec<E>
+  ): Promise<Subscription<E>> {
     const subscriptionId = await this.#api.pod.subscribe(query.schema);
     const emitter = new EventEmitter();
     const subscription = new Subscription(query, emitter, this);