Skip to content

Commit 0aaa14d

Browse files
marcusreinmarcusrein
authored
docs(api-reference): update and extend documentation for api-reference.md (#212)
all checks pass. simple update for docs and the api-reference.md.
1 parent fe83b37 commit 0aaa14d

File tree

1 file changed

+152
-66
lines changed

1 file changed

+152
-66
lines changed

‎docs/docs/api-reference.md‎

Lines changed: 152 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -17,89 +17,78 @@ This section documents the main **Space Events** and the matching client-side he
1717
- [`deleteSpace`](#deletespace)
1818
- [`createInvite`](#createinvite)
1919
- [`acceptInvite`](#acceptinvite)
20-
- [`updateMember`](#updatemember)
21-
- [`removeMember`](#removemember)
20+
- [`createSpaceInbox`](#createspaceinbox)
2221
- [`sendUpdate`](#sendupdate)
2322
- [`sendCompactedUpdate`](#sendcompactedupdate)
2423

2524
---
2625

2726
## Event list
2827

29-
| Event | Helper | HTTP / WS Path | Auth | Description |
30-
|-------|--------|----------------|------|-------------|
31-
| `createSpace` | `createSpace()` | `/spaces` (POST) | **SIWE** + signature | Bootstrap a new Space. |
32-
| `deleteSpace` | `deleteSpace()` | `/spaces/:id` (DELETE) | `admin` | Soft-delete a Space. |
33-
| `createInvite` | `inviteToSpace()` | `/spaces/:id/invites` (POST) | `admin` | Send an encrypted invite. |
34-
| `acceptInvite` | `acceptInvitation()` | `/invites/:id/accept` (POST) | Invite signature | Accept & join Space. |
35-
| `updateMember` | `updateMember()` | `/spaces/:id/members/:accountId` (PATCH) | `admin` | Promote / demote role. |
36-
| `removeMember` | `removeMember()` | `/spaces/:id/members/:accountId` (DELETE) | `admin` | Remove member & rotate keys. |
37-
| `sendUpdate` | _internal_ | `/updates` (WS) | `member` | CRDT patch. |
38-
| `sendCompactedUpdate` | _internal_ | `/updates` (WS) | `member` | Snapshot update log. |
28+
| Event | Helper | HTTP / WS Path | Auth | Description |
29+
| ------------------ | ------------------ | -------------------------------- | ------------------ | ------------------------------------ |
30+
| `createSpace` | `createSpace()` | `/spaces` (POST) | **SIWE** + signature | Bootstrap a new Space. |
31+
| `deleteSpace` | `deleteSpace()` | `/spaces/:id` (DELETE) | `admin` | Soft-delete a Space. |
32+
| `createInvite` | `inviteToSpace()` | `/spaces/:id/invites` (POST) | `admin` | Create an invitation to a Space. |
33+
| `acceptInvite` | `acceptInvitation()` | `/invites/:id/accept` (POST) | Invite signature | Accept an invitation & join a Space. |
34+
| `createSpaceInbox` | `createInbox()` | `/spaces/:id/inboxes` (POST) | `admin` | Create a new inbox in a Space. |
35+
| `sendUpdate` | _internal_ | `/updates` (WS) | `member` | Send a CRDT patch to peers. |
36+
| `sendCompactedUpdate` | _internal_ | `/updates` (WS) | `member` | Send a snapshot of the update log. |
3937

4038
All payloads are JSON objects transported over either:
4139

42-
* **WebSocket** — default for low-latency real-time sync.
43-
* **HTTP** — optional fallback for bootstrapping or server-to-server calls.
40+
- **WebSocket** — default for low-latency real-time sync.
41+
- **HTTP** — optional fallback for bootstrapping or server-to-server calls.
4442

4543
---
4644

4745
## `createSpace`
4846

49-
| | |
50-
|---|---|
51-
| **Method** | `POST /spaces` (HTTP) **or** WebSocket event |
52-
| **Auth** | Signed with the creator's _signature key_ + SIWE cookie |
53-
| **Body** | See JSON-LD below |
54-
| **Success** | `201 Created` with `{ "spaceId": "…" }` |
55-
| **Errors** | `409 AlreadyExists`, `401 Unauthorized`, `422 InvalidSignature` |
56-
57-
```jsonld title="JSON-LD"
58-
{
59-
"@context": "https://schema.org",
60-
"@type": "CreateAction",
61-
"name": "Create Hypergraph Space",
62-
"url": "/spaces",
63-
"application": "Hypergraph",
64-
"instrument": {
65-
"@type": "CryptographicKey",
66-
"name": "spaceKey",
67-
"publicKey": "<base58>"
68-
},
69-
"creator": "did:pkh:eip155:80451:<accountId>"
70-
}
47+
| | |
48+
| --------- | ---------------------------------------------------- |
49+
| **Method** | `POST /spaces` (HTTP) **or** WebSocket event |
50+
| **Auth** | Signed with the creator's _signature key_ + SIWE cookie |
51+
| **Body** | See event schema below. |
52+
| **Success** | `201 Created` with `{ "spaceId": "…" }` |
53+
| **Errors** | `409 AlreadyExists`, `401 Unauthorized`, `422 InvalidSignature` |
54+
55+
### Event Schema
56+
57+
The `CreateSpaceEvent` contains the initial parameters for a new space.
58+
59+
```typescript
60+
export const CreateSpaceEvent = Schema.Struct({
61+
transaction: Schema.Struct({
62+
type: Schema.Literal('create-space'),
63+
id: Schema.String,
64+
creatorAccountId: Schema.String,
65+
}),
66+
author: EventAuthor, // { accountId: string, signature: { hex: string, recovery: number } }
67+
});
7168
```
7269

73-
### Parameters
74-
75-
| Name | Type | Required | Description |
76-
|------|------|----------|-------------|
77-
| `ciphertext` | `string(base64)` | ✔︎ | Encrypted Automerge init document. |
78-
| `nonce` | `string(base64)` | ✔︎ | Nonce used for XChaCha20-Poly1305. |
79-
| `memberSignaturePublicKey` | `string(base58)` | ✔︎ | Ed25519 public key. |
80-
| `memberEncryptionPublicKey` | `string(base58)` | ✔︎ | X25519 public key. |
81-
| `keyBox` | `object` | ✔︎ | Space key encrypted for the creator. |
82-
83-
### Request example
70+
### Request Example
8471

8572
```json title="POST /spaces"
8673
{
8774
"eventId": "6db7b5f0",
8875
"spaceId": "efc45a11",
89-
"ciphertext": "v8Qe…",
90-
"nonce": "A0nx…",
91-
"memberSignaturePublicKey": "9bEe…",
92-
"memberEncryptionPublicKey": "e1F3…",
93-
"keyBox": {
94-
"ciphertext": "3k0i…",
95-
"recipientPublicKey": "e1F3…",
96-
"authorPublicKey": "9bEe…"
76+
"transaction": {
77+
"type": "create-space",
78+
"id": "efc45a11",
79+
"creatorAccountId": "did:pkh:eip155:1:0x123..."
9780
},
98-
"signature": "MEUCIQD…"
81+
"author": {
82+
"accountId": "did:pkh:eip155:1:0x123...",
83+
"signature": {
84+
"hex": "0xabc...",
85+
"recovery": 1
86+
}
87+
}
9988
}
10089
```
10190

102-
### Response example
91+
### Response Example
10392

10493
```json title="201 Created"
10594
{
@@ -111,30 +100,127 @@ All payloads are JSON objects transported over either:
111100

112101
## `deleteSpace`
113102

114-
> TODO — coming in the next version.
103+
| | |
104+
| --------- | ---------------------------------------------------- |
105+
| **Method** | `DELETE /spaces/:id` (HTTP) **or** WebSocket event |
106+
| **Auth** | `admin` role in the space |
107+
| **Success** | `200 OK` |
108+
| **Errors** | `401 Unauthorized`, `404 NotFound` |
109+
110+
### Event Schema
111+
112+
The `DeleteSpaceEvent` marks a space for soft-deletion. It requires referencing the hash of the previous event to maintain chain integrity.
113+
114+
```typescript
115+
export const DeleteSpaceEvent = Schema.Struct({
116+
transaction: Schema.Struct({
117+
type: Schema.Literal('delete-space'),
118+
id: Schema.String, // The ID of the space to delete
119+
previousEventHash: Schema.String,
120+
}),
121+
author: EventAuthor,
122+
});
123+
```
115124

116125
---
117126

118127
## `createInvite`
119128

120-
> TODO — coming in the next version.
129+
| | |
130+
| --------- | ---------------------------------------------------- |
131+
| **Method** | `POST /spaces/:id/invites` (HTTP) **or** WebSocket event |
132+
| **Auth** | `admin` role in the space |
133+
| **Success** | `201 Created` |
134+
| **Errors** | `401 Unauthorized`, `404 NotFound`, `422 Unprocessable Entity` |
135+
136+
### Event Schema
137+
138+
The `CreateInvitationEvent` creates a new single-use invitation for an account to join the space.
139+
140+
```typescript
141+
export const CreateInvitationEvent = Schema.Struct({
142+
transaction: Schema.Struct({
143+
type: Schema.Literal('create-invitation'),
144+
id: Schema.String, // The ID of the space
145+
inviteeAccountId: Schema.String, // The account ID of the user being invited
146+
previousEventHash: Schema.String,
147+
}),
148+
author: EventAuthor,
149+
});
150+
```
151+
152+
---
153+
154+
## `acceptInvite`
155+
156+
| | |
157+
| --------- | ---------------------------------------------------- |
158+
| **Method** | `POST /invites/:id/accept` (HTTP) **or** WebSocket event |
159+
| **Auth** | Signature from the invited account |
160+
| **Success** | `200 OK` |
161+
| **Errors** | `401 Unauthorized`, `404 NotFound` |
162+
163+
### Event Schema
164+
165+
The `AcceptInvitationEvent` is created when a user accepts an invitation to join a space. This adds them to the member list.
166+
167+
```typescript
168+
export const AcceptInvitationEvent = Schema.Struct({
169+
transaction: Schema.Struct({
170+
type: Schema.Literal('accept-invitation'),
171+
id: Schema.String, // The ID of the space
172+
previousEventHash: Schema.String,
173+
}),
174+
author: EventAuthor, // The new member
175+
});
176+
```
177+
178+
---
179+
180+
## `createSpaceInbox`
181+
182+
| | |
183+
| --------- | ---------------------------------------------------- |
184+
| **Method** | `POST /spaces/:id/inboxes` (HTTP) **or** WebSocket event |
185+
| **Auth** | `admin` role in the space |
186+
| **Success** | `201 Created` |
187+
| **Errors** | `401 Unauthorized`, `404 NotFound` |
188+
189+
### Event Schema
190+
191+
The `CreateSpaceInboxEvent` creates a new inbox within a space, which can be used for direct or broadcast messaging between members.
192+
193+
```typescript
194+
export const CreateSpaceInboxEvent = Schema.Struct({
195+
transaction: Schema.Struct({
196+
type: Schema.Literal('create-space-inbox'),
197+
id: Schema.String, // The ID of the new inbox
198+
spaceId: Schema.String, // The ID of the space
199+
inboxId: Schema.String,
200+
encryptionPublicKey: Schema.String,
201+
secretKey: Schema.String, // Should be encrypted
202+
isPublic: Schema.Boolean,
203+
authPolicy: InboxSenderAuthPolicy, // 'all-members' | 'admins-only' | 'self-only'
204+
previousEventHash: Schema.String,
205+
}),
206+
author: EventAuthor,
207+
});
208+
```
121209

122210
---
123211

124212
## More endpoints
125213

126-
The remaining endpoints follow the same structure. Until full documentation lands, refer to **type definitions** exported from the SDK:
214+
The remaining endpoints (`sendUpdate`, `sendCompactedUpdate`) are used internally for state synchronization and are not typically called directly. For a deeper understanding of the entire event-sourcing model, you can refer to the type definitions exported from the SDK:
127215

128216
```ts
129-
import {
130-
Messages,
131-
SpaceEvents,
132-
Inboxes,
133-
} from '@graphprotocol/hypergraph';
217+
import { SpaceEvents } from '@graphprotocol/hypergraph';
218+
219+
// e.g., SpaceEvents.CreateSpaceEvent
134220
```
135221

136222
---
137223

138224
### Edit on GitHub
139225

140-
[✏️ Improve this page](https://github.com/graphprotocol/hypergraph/edit/main/docs/docs/api-reference.md)
226+
[✏️ Improve this page](https://github.com/graphprotocol/hypergraph/edit/main/docs/docs/api-reference.md)

0 commit comments

Comments
 (0)