๐ API Reference
This section documents the main Space Events and the matching client-side helpers in @graphprotocol/hypergraph
and @graphprotocol/hypergraph-react
.
โน๏ธ The SDK abstracts most serialization, encryption and validation. You'll rarely emit raw events yourselfโHooks and helper functions should cover 95 % of use-cases. Still, understanding their wire format helps with debugging and server integration.
Table of Contentsโ
Event listโ
Event | Helper | HTTP / WS Path | Auth | Description |
---|---|---|---|---|
createSpace | createSpace() | /spaces (POST) | SIWE + signature | Bootstrap a new Space. |
deleteSpace | deleteSpace() | /spaces/:id (DELETE) | admin | Soft-delete a Space. |
createInvite | inviteToSpace() | /spaces/:id/invites (POST) | admin | Create an invitation to a Space. |
acceptInvite | acceptInvitation() | /invites/:id/accept (POST) | Invite signature | Accept an invitation & join a Space. |
createSpaceInbox | createInbox() | /spaces/:id/inboxes (POST) | admin | Create a new inbox in a Space. |
sendUpdate | internal | /updates (WS) | member | Send a CRDT patch to peers. |
sendCompactedUpdate | internal | /updates (WS) | member | Send a snapshot of the update log. |
All payloads are JSON objects transported over either:
- WebSocket โ default for low-latency real-time sync.
- HTTP โ optional fallback for bootstrapping or server-to-server calls.
createSpace
โ
Method | POST /spaces (HTTP) or WebSocket event |
Auth | Signed with the creator's signature key + SIWE cookie |
Body | See event schema below. |
Success | 201 Created with { "spaceId": "โฆ" } |
Errors | 409 AlreadyExists , 401 Unauthorized , 422 InvalidSignature |
Event Schemaโ
The CreateSpaceEvent
contains the initial parameters for a new space.
export const CreateSpaceEvent = Schema.Struct({
transaction: Schema.Struct({
type: Schema.Literal('create-space'),
id: Schema.String,
creatorAccountId: Schema.String,
}),
author: EventAuthor, // { accountId: string, signature: { hex: string, recovery: number } }
});
Request Exampleโ
{
"eventId": "6db7b5f0",
"spaceId": "efc45a11",
"transaction": {
"type": "create-space",
"id": "efc45a11",
"creatorAccountId": "did:pkh:eip155:1:0x123..."
},
"author": {
"accountId": "did:pkh:eip155:1:0x123...",
"signature": {
"hex": "0xabc...",
"recovery": 1
}
}
}
Response Exampleโ
{
"spaceId": "efc45a11"
}
deleteSpace
โ
Method | DELETE /spaces/:id (HTTP) or WebSocket event |
Auth | admin role in the space |
Success | 200 OK |
Errors | 401 Unauthorized , 404 NotFound |
Event Schemaโ
The DeleteSpaceEvent
marks a space for soft-deletion. It requires referencing the hash of the previous event to maintain chain integrity.
export const DeleteSpaceEvent = Schema.Struct({
transaction: Schema.Struct({
type: Schema.Literal('delete-space'),
id: Schema.String, // The ID of the space to delete
previousEventHash: Schema.String,
}),
author: EventAuthor,
});
createInvite
โ
Method | POST /spaces/:id/invites (HTTP) or WebSocket event |
Auth | admin role in the space |
Success | 201 Created |
Errors | 401 Unauthorized , 404 NotFound , 422 Unprocessable Entity |
Event Schemaโ
The CreateInvitationEvent
creates a new single-use invitation for an account to join the space.
export const CreateInvitationEvent = Schema.Struct({
transaction: Schema.Struct({
type: Schema.Literal('create-invitation'),
id: Schema.String, // The ID of the space
inviteeAccountId: Schema.String, // The account ID of the user being invited
previousEventHash: Schema.String,
}),
author: EventAuthor,
});
acceptInvite
โ
Method | POST /invites/:id/accept (HTTP) or WebSocket event |
Auth | Signature from the invited account |
Success | 200 OK |
Errors | 401 Unauthorized , 404 NotFound |
Event Schemaโ
The AcceptInvitationEvent
is created when a user accepts an invitation to join a space. This adds them to the member list.
export const AcceptInvitationEvent = Schema.Struct({
transaction: Schema.Struct({
type: Schema.Literal('accept-invitation'),
id: Schema.String, // The ID of the space
previousEventHash: Schema.String,
}),
author: EventAuthor, // The new member
});
createSpaceInbox
โ
Method | POST /spaces/:id/inboxes (HTTP) or WebSocket event |
Auth | admin role in the space |
Success | 201 Created |
Errors | 401 Unauthorized , 404 NotFound |
Event Schemaโ
The CreateSpaceInboxEvent
creates a new inbox within a space, which can be used for direct or broadcast messaging between members.
export const CreateSpaceInboxEvent = Schema.Struct({
transaction: Schema.Struct({
type: Schema.Literal('create-space-inbox'),
id: Schema.String, // The ID of the new inbox
spaceId: Schema.String, // The ID of the space
inboxId: Schema.String,
encryptionPublicKey: Schema.String,
secretKey: Schema.String, // Should be encrypted
isPublic: Schema.Boolean,
authPolicy: InboxSenderAuthPolicy, // 'all-members' | 'admins-only' | 'self-only'
previousEventHash: Schema.String,
}),
author: EventAuthor,
});
More endpointsโ
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:
import { SpaceEvents } from '@graphprotocol/hypergraph';
// e.g., SpaceEvents.CreateSpaceEvent