docs: full module READMEs (v0.8.103 platform audit)
This commit is contained in:
Raven Scott
@@ -1,28 +1,123 @@
|
||||
# pearcord-shared
|
||||
|
||||
IDs, topics, RPC constants, and message formatting helpers.
|
||||
Cross-cutting constants, topic naming, RPC framing, permission helpers, message formatting, and deep-link utilities shared by every Pearcord module.
|
||||
|
||||
Part of **[Pearcord](https://git.ssh.surf/pearcord)** — 100% peer-to-peer community chat on [Pear](https://pear.holepunch.to). No central servers.
|
||||
## Mission
|
||||
|
||||
Provide a single source of truth for HyperDB collection names, channel and member enums, gossip RPC method IDs, Hyperswarm topic strings, and local permission bitmask checks. Avoid duplicating wire formats or ID generation across guild, DM, platform, and bot packages.
|
||||
|
||||
## When to use / not
|
||||
|
||||
**Use when:**
|
||||
|
||||
- You need `COLLECTIONS`, `RPC`, `CHANNEL_TYPES`, or topic helpers (`guildTopic`, `dmTopic`, `encodeRpc`).
|
||||
- You enforce send/view/voice permissions with `memberCanParticipate`, `memberHasPermission`, or `canModifyMessage`.
|
||||
- You parse or emit `pearcord://` deep links or format message HTML / mentions.
|
||||
|
||||
**Do not use when:**
|
||||
|
||||
- You need persistence — use `pearcord-db`.
|
||||
- You need Hyperswarm sessions — use `pearcord-guild` or `pearcord-dm`.
|
||||
- You need a full app API — use `pearcord-platform`.
|
||||
|
||||
## Public API
|
||||
|
||||
| Export | Role |
|
||||
|--------|------|
|
||||
| `COLLECTIONS` | HyperDB / JSON collection keys (`@pearcord/users`, …) |
|
||||
| `CHANNEL_TYPES`, `USER_STATUS`, `MEMBER_ROLES` | Domain enums |
|
||||
| `PERMISSION`, `ROLE_PERMISSIONS` | Bitmask permission model |
|
||||
| `memberCanParticipate`, `memberCanViewChannel`, `memberCanConnectVoice`, `memberCanSpeakInVoice`, `memberCanJoinVoiceListenOnly` | Effective-mask aware checks |
|
||||
| `memberHasPermission`, `roleHasPermission`, `canModifyMessage` | Moderation / edit rules |
|
||||
| `RPC` | Numeric gossip method IDs (1–79) |
|
||||
| `id`, `discriminator`, `now` | ID and timestamp helpers |
|
||||
| `guildTopic`, `dmTopic`, `groupDmTopic`, `contactsTopic`, `settingsTopic`, `userPrefsTopic`, `profileCosmeticsTopic`, `deviceSyncTopic` | Hyperswarm topic strings |
|
||||
| `dmChannelId`, `groupDmChannelId`, `normalizeGroupParticipants`, `GROUP_DM_MIN`, `GROUP_DM_MAX` | DM / group DM identity |
|
||||
| `topicToBuffer` | Hash topic → swarm discovery key |
|
||||
| `encodeRpc`, `decodeRpc` | `compact-encoding` RPC frame (uint8 method + uint length + raw payload) |
|
||||
| `formatMessageContent`, `extractMentionNames`, `extractFirstUrl`, `linkPreviewMeta`, `buildLinkPreviewHtml`, `buildRichEmbedHtml`, `linkifyMessageHtml` | Message rendering |
|
||||
| `resolveMentionedUserIds` | `@name` → user id resolution |
|
||||
| `PEARCORD_SCHEME`, `isPearcordDeepLink`, `findPearcordDeepLinkInArgv`, `parsePearcordDeepLink`, `formatPearcordDeepLink`, `formatGuildDeepLink`, `formatInviteDeepLink`, `formatDevicePairDeepLink` | OS / argv deep links |
|
||||
| `DEVICE_PAIR_PREFIX` | `pcdv_` device pairing codes |
|
||||
|
||||
Submodules: `./format-message`, `./mentions`, `./deep-links` (re-exported from `index.js`).
|
||||
|
||||
## P2P surface
|
||||
|
||||
| Surface | Detail |
|
||||
|---------|--------|
|
||||
| RPC framing | `encodeRpc(method, payloadBuf)` / `decodeRpc(buf)` — used by guild gossip (`pearcord-gossip-v1`), DM mesh, contacts, settings |
|
||||
| Topics | Deterministic strings hashed via `topicToBuffer` for Hyperswarm `join` |
|
||||
| RPC constants | Payloads are JSON inside frames; method IDs defined in `RPC` |
|
||||
|
||||
No network code lives in this package.
|
||||
|
||||
## Storage
|
||||
|
||||
None. Pure utilities and constants.
|
||||
|
||||
## Platform integration
|
||||
|
||||
`pearcord-platform` imports a large subset for permissions, deep links, search indexing helpers (`id`, `now`), and inbound message policy (`canModifyMessage`, `memberCanParticipate`, `COLLECTIONS`).
|
||||
|
||||
Other modules (`pearcord-guild`, `pearcord-message`, `pearcord-invite`, `pearcord-identity`, smoke scripts) depend on this package directly.
|
||||
|
||||
## UI / IPC
|
||||
|
||||
Not used by IPC directly. UI receives permission outcomes and formatted HTML from the platform sidecar, which uses these helpers internally.
|
||||
|
||||
Deep-link argv parsing is used by companion and desktop startup flows via platform + `pearcord-protocol`.
|
||||
|
||||
## Related docs
|
||||
|
||||
- [MODULES.md](../../docs/MODULES.md) — package map
|
||||
- [PERMISSIONS.md](../../docs/PERMISSIONS.md) — role bitmask semantics
|
||||
- [ROLE_PERMISSIONS.md](../../docs/ROLE_PERMISSIONS.md) — built-in roles
|
||||
- [CHANNEL_PERMISSIONS.md](../../docs/CHANNEL_PERMISSIONS.md) — overwrites + effective mask
|
||||
- [PEARCORD_PROTOCOL.md](../../docs/PEARCORD_PROTOCOL.md) — `pearcord://` URLs
|
||||
- [MESSAGE_DEEP_LINKS.md](../../docs/MESSAGE_DEEP_LINKS.md) — jump links
|
||||
- [INVITE_DEEP_LINKS.md](../../docs/INVITE_DEEP_LINKS.md) — invite URLs
|
||||
- [GUILD_SYNC.md](../../docs/GUILD_SYNC.md) — `RPC.GUILD_SYNC` payload
|
||||
- [HOLEPUNCH_STACK.md](../../docs/HOLEPUNCH_STACK.md) — Hyperswarm stack context
|
||||
|
||||
## Tests
|
||||
|
||||
No unit tests in this package. Exercised indirectly via `apps/pearcord` smoke scripts that import `RPC`, `COLLECTIONS`, `CHANNEL_TYPES`, or deep-link helpers (for example `smoke-voice-speaking-mesh.cjs`, `smoke-device-pair-deep-link.cjs`, `smoke-guild-sync.cjs`).
|
||||
|
||||
## Code example
|
||||
|
||||
```javascript
|
||||
const {
|
||||
RPC,
|
||||
guildTopic,
|
||||
topicToBuffer,
|
||||
encodeRpc,
|
||||
memberCanParticipate,
|
||||
id
|
||||
} = require('pearcord-shared')
|
||||
const b4a = require('b4a')
|
||||
|
||||
const guildId = id()
|
||||
const topic = guildTopic(guildId)
|
||||
const discoveryKey = topicToBuffer(topic)
|
||||
|
||||
const frame = encodeRpc(RPC.MESSAGE_CREATE, b4a.from(JSON.stringify({
|
||||
id: id(),
|
||||
channelId: 'ch1',
|
||||
content: 'hello'
|
||||
})))
|
||||
|
||||
const allowed = memberCanParticipate(
|
||||
{ roles: 'member', customRoleIds: [] },
|
||||
[],
|
||||
null
|
||||
)
|
||||
```
|
||||
|
||||
## Repository
|
||||
|
||||
Part of **[Pearcord](https://git.ssh.surf/pearcord)** — peer-to-peer community chat on [Pear](https://pear.holepunch.to).
|
||||
|
||||
- **Org:** [`pearcord`](https://git.ssh.surf/pearcord)
|
||||
- **Clone:** `git clone https://git.ssh.surf/pearcord/pearcord-shared.git`
|
||||
|
||||
## Install (npm)
|
||||
|
||||
```bash
|
||||
npm install git+https://git.ssh.surf/pearcord/pearcord-shared.git#main
|
||||
```
|
||||
|
||||
## Stack
|
||||
|
||||
Hyperswarm · HyperDB · Protomux · Pear / Bare
|
||||
|
||||
## Documentation
|
||||
|
||||
See [`pearcord/pearcord-docs`](https://git.ssh.surf/pearcord/pearcord-docs) for architecture, roadmap, and IPC reference.
|
||||
|
||||
## License
|
||||
|
||||
Pearcord modules are developed for the Pearcord platform. See the org README for contribution guidelines.
|
||||
- **Install:** `npm install git+https://git.ssh.surf/pearcord/pearcord-shared.git#main`
|
||||
|
||||
@@ -273,7 +273,9 @@ const RPC = {
|
||||
HOOK_FAILURE_DIGEST_CSV_SYNC: 75,
|
||||
AUDIT_EXPORT_CSV_SYNC: 76,
|
||||
MESSAGE_SEARCH_REQUEST: 77,
|
||||
MESSAGE_SEARCH_RESPONSE: 78
|
||||
MESSAGE_SEARCH_RESPONSE: 78,
|
||||
/** Ephemeral voice activity for sidebar roster (v0.8.101). */
|
||||
VOICE_SPEAKING: 79
|
||||
}
|
||||
|
||||
const DEVICE_PAIR_PREFIX = 'pcdv_'
|
||||
|
||||
Reference in New Issue
Block a user