Add/improve package READMEs

packages/app-connector-react/README.md

@@ -0,0 +1,71 @@
+# @parcnet-js/app-connector-react
+
+React bindings for the Parcnet app connector library.
+
+## Installation
+
+Using npm:
+
+    npm install @parcnet-js/app-connector-react
+
+Using yarn:
+
+    yarn add @parcnet-js/app-connector-react
+
+Using pnpm:
+
+    pnpm add @parcnet-js/app-connector-react
+
+## Usage
+
+Basic usage with the ParcnetClientProvider:
+
+    import { ParcnetClientProvider } from "@parcnet-js/app-connector-react";
+    import type { Zapp } from "@parcnet-js/app-connector";
+
+    // Create your Zapp instance
+    const zapp: Zapp = {
+      name: "My Zapp Name",
+      permissions: {
+        REQUEST_PROOF: { collections: ["My Collection"] },
+        SIGN_POD: {},
+        READ_POD: { collections: ["My Collection"] },
+        INSERT_POD: { collections: ["My Collection"] },
+        DELETE_POD: { collections: ["My Collection"] },
+        READ_PUBLIC_IDENTIFIERS: {}
+      }
+    };
+
+    function App() {
+      return (
+        <ParcnetClientProvider 
+          zapp={zapp}
+          url="https://zupass.org" // Optional, defaults to https://zupass.org
+        >
+          {/* Your app content */}
+        </ParcnetClientProvider>
+      );
+    }
+
+Using the context in your components:
+
+    import { useParcnetClient, ClientConnectionState } from '@parcnet-js/app-connector-react';
+
+    function MyComponent() {
+      const { connectionState, connect, disconnect, z } = useParcnetClientContext();
+
+      if (connectionState === ClientConnectionState.CONNECTED) {
+        // Access the Parcnet API through 'z'
+        // e.g. await z.identity.getPublicKey()
+      }
+    }
+
+## Documentation
+
+For detailed documentation and API reference, please visit our [documentation site](https://zappsdk.netlify.app/guides/getting-started/).
+
+
+
+
+
+

packages/app-connector/README.md

@@ -29,80 +29,4 @@ 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.
+See [the documentation](https://zappsdk.netlify.app/guides/getting-started/) for details of the API methods, their parameters, and results.

packages/ticket-spec/README.md

@@ -0,0 +1,85 @@
+# Ticket Spec
+
+Provides a [PodSpec](https://www.npmjs.com/package/@parcnet-js/podspec) schema for tickets in Zupass.
+
+## Installation
+
+Install the package:
+
+Using npm:
+
+    npm install @parcnet-js/ticket-spec
+
+Using yarn:
+
+    yarn add @parcnet-js/ticket-spec
+
+Using pnpm:
+
+    pnpm add @parcnet-js/ticket-spec
+
+## Usage
+
+This package has two main exports: the `TicketSpec` object, and the `ticketProofRequest` function.
+
+The `TicketSpec` object describes a ticket POD and can be used to validate a POD, query a POD collection, or transform suitable JavaScript objects to POD entries:
+
+```ts
+import { TicketSpec } from "@parcnet-js/ticket-spec";
+
+const somePod = { /* a POD from some external source */ };
+const result = TicketSpec.safeParse(somePod);
+if (result.isValid) {
+  // somePod is a valid Ticket POD
+}
+
+const pods: POD[] = [/* PODs from some external source */];
+// Find the Ticket PODs in the collection:
+const ticketPods = TicketSpec.query(pods);
+
+const ticketData = {
+  ticketName: "My ticket",
+  attendeeName: "John Doe",
+  // ... other ticket data
+};
+const result = TicketSpec.safeParseEntries(ticketData, { coerce: true });
+if (result.isValid) {
+  // result.value contains PODEntries for a Ticket POD, ready to be signed
+}
+```
+
+Often we care about tickets for specific events, rather than tickets in general. In this case, we can extend the TicketSpec object by constraining the valid values for entries like `eventId`. For example, if we want to match on a primary Devcon ticket, we could extend TicketSpec as follows:
+
+```ts
+const DevconTicketSpec = TicketSpec.extend((schema, f) => {
+  return f({
+    ...schema,
+    entries: {
+      // Include all of the regular ticket entries:
+      ...schema.entries,
+      // Make sure the ticket is for the Devcon event:
+      eventId: {
+        type: "string",
+        isMemberOf: [
+          { type: "string", value: "5074edf5-f079-4099-b036-22223c0c6995" },
+        ],
+      },
+      // To target the user's main Devcon ticket, we exclude add-on (swag) tickets.
+      // This rule excludes tickets which have an `isAddon` entry with a value of `1`.
+      isAddon: {
+        type: "optional",
+        innerType: {
+          type: "int",
+          isNotMemberOf: [{ type: "int", value: BigInt(1) }],
+        },
+      },
+    },
+    signerPublicKey: {
+      // Must be the Devcon ticket issuance public key
+      isMemberOf: ["YwahfUdUYehkGMaWh0+q3F8itx2h8mybjPmt8CmTJSs"],
+    },
+  });
+});
+```
+
+You can now use `DevconTicketSpec` in place of the plain `TicketSpec`, and it will perform the same operations: validating that a ticket is a Devcon ticket, finding a Devcon ticket from a collection, and turning JavaScript data into Devcon ticket entries.