update docs (#293)

Author: nikgraf

docs/docs/intro.md

@@ -20,6 +20,40 @@ It has one mandatory prop: `mapping`. This is the mapping of your schema to the
 
 Further it has an optional prop: `syncServerUri`. This is the URL of the sync server. By default it is set to `https://hypergraph.fly.dev`.
 
+## useHypergraphApp
+
+The `useHypergraphApp` is available inside the `HypergraphAppProvider` and manages the sync server connection and provides serveral useful functions.
+
+```tsx
+import { useHypergraphApp } from "@graphprotocol/hypergraph-react";
+
+const App = () => {
+  const { isConnected, logout } = useHypergraphApp();
+  return <div>{isConnecting ? "Connecting..."}</div>;
+};
+```
+
+- `isConnected` is a boolean that indicates that syncing private spaces is not yet possible. You need to wait until it's `false` to query data from private spaces.
+- `logout` is a function that logs out the user.
+
+There are serveral more that will be explained in the following sections.
+
+## useHypergraphAuth
+
+The `useHypergraphAuth` is available inside the `HypergraphAppProvider` and manages the authentication state and provides serveral useful functions.
+
+```tsx
+import { useHypergraphAuth } from "@graphprotocol/hypergraph-react";
+
+const App = () => {
+  const { authenticated, identity } = useHypergraphAuth();
+  return <div>{authenticated ? "Authenticated" : "Not authenticated"}</div>;
+};
+```
+
+- `authenticated` is a boolean that indicates if the user is authenticated.
+- `identity` is the identity of the logged in user.
+
 ## HypergraphSpaceProvider
 
 Whenever interact with a space you need to provide the space ID. In order providing the space ID to every hook e.g. useSpace, useQuery, useCreateEntity, etc. you can use the `HypergraphSpaceProvider` to wrap a section of your app with the space ID.
@@ -45,3 +79,4 @@ const SpaceDetails = () => {
 ```
 
 The `space` prop is the ID of the space. It can be a private or public space.
+

docs/docs/providers.md

@@ -2,39 +2,69 @@
 
 Once you want to share your data with the world you need to publish it. This is done by creating the necessary `Opertations` (Ops) and then publishing them.
 
-## Prepare Publish (not yet supported)
+## Prepare Publish
 
 Based on entity Ids, the source space and the target space this function calculates the necessary `Operations` to publish the data.
 
 ```tsx
 import { preparePublish } from "@graphprotocol/hypergraph-react";
 
-const { ops, diff } = preparePublish({
-  entityIds: ["entity-id-1", "entity-id-2"],
-  privateSourceSpace: "private-source-space-id",
-  publicTargetSpace: "public-target-space-id",
+const { ops } = preparePublish({
+  entity: entity,
+  publicSpace: "public-space-id",
 });
 ```
 
-## Publishing Relations
+The entity can come from a `useCreateEntity` result or from a `useQuery` result e.g.
 
 ```tsx
-import { publishOps } from '@graphprotocol/hypergraph-react';
+const MyComponent = () => {
+  const { data: events } = useQuery(Event, { mode: "private" });
+
+  const createOpsForPublishing = async (event) => {
+    const { ops } = preparePublish({
+      entity: event,
+      publicSpace: "public-space-id",
+    });
+  };
+
+  return (
+    <div>
+      {events.map((event) => (
+        <button key={event.id} onClick={() => createOpsForPublishing(event)}>
+          {event.name}
+        </button>
+      ))}
+    </div>
+  );
+};
+```
+
+## Publish
+
+The `publishOps` function is used to publish the changes to the public space. Here is a full example flow:
+
+```tsx
+import { publishOps } from "@graphprotocol/hypergraph-react";
 
 const MyComponent = () => {
   const { getSmartSessionClient } = useHypergraphApp();
 
   const publishChanges = async () => {
     const smartSessionClient = await getSmartSessionClient();
+    const publicSpaceId = "public-space-id";
 
-    const ops = […];
+    const { ops } = preparePublish({
+      entity: entity,
+      publicSpace: publicSpaceId,
+    });
 
     const result = await publishOps({
       ops,
       walletClient: smartSessionClient,
-      space,
-      name: 'Create Job Offers',
+      space: publicSpaceId,
+      name: "Create Job Offers",
     });
-  }
-}
+  };
+};
 ```

docs/docs/publishing-public-data.md

@@ -51,7 +51,8 @@ useQuery for private data returns:
 
 - data - a list of entities defined in your schema
 - invalidEntities - a list of entities that are in your space storage with correct type, but can't be parsed to your schema
+- deleted - a list of entities that are marked as deleted, we keep them around to be able to later be able to publish the deleted information to the public knowledge graph
 
 ```ts
-const { data, invalidEntities } = useQuery(Event, { mode: 'private' });
+const { data, invalidEntities, deleted } = useQuery(Event, { mode: 'private' });
 ```

docs/docs/query-private-data.md

@@ -5,7 +5,11 @@ version: 0.0.1
 tags: [quickstart, typesync]
 ---
 
-# 🚀 Quickstart: An existing example app
+# 🚀 Quickstart
+
+If you just want to get started and get a feel for how Hypergraph works, we have created an example app that you can clone and use as a starting point.
+
+## Explore the Example app
 
 In order to get started as fast as possible we have created an example app that you can clone and use as a starting point.
 
@@ -18,65 +22,59 @@ pnpm dev
 
 Open the browser, navigate to `http://localhost:5173` and you should see the app running.
 
-# 🚀 Quickstart: Your First Hypergraph App
+## Create a new app using TypeSync
 
-In case you want to define your own schema and mapping you can follow the guide below.
+In case you want build an app with your own data types you can follow the guide below.
 
 It will walk you through creating a new, fully-functional React application powered by Hypergraph using our scaffolding tool, **TypeSync**. In just a few minutes, you'll have a local development environment up and running.
 
-This approach is perfect for developers who want to quickly build an application on top of Hypergraph without needing to set up the entire monorepo infrastructure.
-
-## Prerequisites
+### Prerequisites
 
 - Node.js >= 22
 - pnpm >= 10 (install with `npm install -g pnpm`)
 
-## 1. Get the Hypergraph Toolkit
+### 1. Install the Hypergraph CLI
 
 First, clone the Hypergraph repository, which contains TypeSync.
 
 ```bash
-git clone https://github.com/graphprotocol/hypergraph.git
-cd hypergraph
+npm install -g @graphprotocol/hypergraph-cli@latest
 ```
 
-Next, install dependencies and build the required packages. This step ensures that TypeSync and all its components are ready to use.
+When using `pnpm` you need to v10 or higher
 
 ```bash
-pnpm install
-pnpm build
+pnpm install -g @graphprotocol/hypergraph-cli@latest
+pnpm approve-builds -g
+# select @tailwindcss/oxide, better-sqlite3, and esbuild
 ```
 
-## 2. Launch TypeSync
-
-TypeSync is a visual tool that helps you define your data schema and then generates a complete starter application based on your design.
+### 2. Launch TypeSync
 
-Navigate to the `typesync` app and start its development server:
+TypeSync is a visual tool that helps you define your data schema and then generates a complete starter application based on your design. Launch it with
 
 ```bash
-cd apps/typesync
-pnpm dev
+hg typesync --open
 ```
 
-This will start the TypeSync server. You can now access the **TypeSync Studio** in your browser at `http://localhost:4000`.
+This will start the TypeSync server. You can now access the **TypeSync** app in your browser at `http://localhost:3000`.
 
-## 3. Scaffold Your Application
+### 3. Scaffold Your Application
 
 In the TypeSync Studio:
 
 1.  Give your new application a name and a short description.
-2.  Use the visual editor to define your data models (we call them "types"). For example, you could create a `Post` type with a `title` (Text) and `content` (Text) properties.
+2.  Use the visual editor to define your data models (we call them "types"). For example, you could create a `Post` type with a `name` (Text) and `content` (Text) properties.
 3.  When you're ready, click "Generate App".
 
-TypeSync will create a new directory for your application (e.g., `./my-awesome-app`) within the `hypergraph` monorepo, containing all the files and dependencies you need.
+TypeSync will create a new directory for your application (e.g., `./my-awesome-app`) containing all the files and dependencies you need.
 
-## 4. Run Your New App
+### 4. Run Your New App
 
 Once your app is generated, open a **new terminal tab**. Navigate into the newly created app directory, install its dependencies, and start the local development server.
 
 ```bash
-# In a new terminal, from the `hypergraph/apps/typesync` directory
-cd ../../my-awesome-app  # Adjust the path to match your app's name
+cd ./my-awesome-app  # Adjust the path to match your app's name
 pnpm install
 pnpm dev
 ```
@@ -87,7 +85,7 @@ You're all set! You can now start building your application by editing the files
 
 ---
 
-### Edit on GitHub :bust_in_silhouette:
+## Edit on GitHub :bust_in_silhouette:
 
 [✏️ Improve this page](https://github.com/graphprotocol/hypergraph/edit/main/docs/docs/quickstart.md)
 

docs/docs/quickstart.md

@@ -103,8 +103,8 @@ const config = {
             title: 'Docs',
             items: [
               {
-                label: 'Tutorial',
-                to: '/docs/intro',
+                label: 'Quickstart',
+                to: '/docs/quickstart',
               },
             ],
           },
@@ -127,9 +127,9 @@ const config = {
               {
                 label: 'Geo',
                 to: 'https://geobrowser.io',
-              }
+              },
             ],
-          }
+          },
         ],
         copyright: `Copyright © ${new Date().getFullYear()} Geo Browser & contributors.`,
       },