# Pubky Writes

> Guide for writing data to Pubky homeservers from Eventky. Use when implementing create/update/delete operations, working with the pubky SDK, or debugging write failures and data validation errors. Use when this capability is needed.

- Skill: `tomevault-io/pubky-writes` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/pubky-writes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/pubky-writes/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/pubky-writes

---


# Writing Data to Pubky Homeservers

## Architecture
Eventky uses `@synonymdev/pubky` SDK to write JSON data to user-owned homeservers.
Data is stored at well-known paths under the user's public key.

## Write Pattern

```typescript
// 1. Build the data object matching pubky-app-specs model
const event: PubkyAppEvent = { ... };

// 2. Validate using WASM (pubky-app-specs)
// This MUST happen before writing — it's the enforcement layer
const validated = validateEvent(event);

// 3. Construct the path
const path = `/pub/eventky.app/events/${generateTimestampId()}`;

// 4. Write to homeserver
await pubky.put(path, JSON.stringify(validated));

// 5. Optimistically update local cache
updateOptimisticCache('events', path, validated);
```

## Namespaces
- Social features (users, posts, files, tags, bookmarks, follows, feeds): `pubky.app`
- Calendar features (calendars, events, attendees): `eventky.app`

## ID Generation
- **Timestamp IDs**: Crockford Base32 encoded current time (events, calendars, posts, files)
- **Hash IDs**: Blake3 hash of deterministic inputs (tags, bookmarks, attendees)
- NEVER generate random UUIDs — IDs must be deterministic and reproducible

## Delete Pattern
Writing `[DELETED]` as content marks an entity as deleted.
The actual homeserver record persists but Nexus treats it as removed.

## Update Pattern
- Increment `sequence` field on the entity
- Update `last_modified` to current Unix microseconds
- Write the full updated object to the same path (PUT replaces)

## Error Handling
- WASM validation errors → show user-friendly message, don't attempt write
- Network errors → retry with exponential backoff
- Auth errors → redirect to re-authentication flow (see @docs/AUTH.md)

## Critical Rules
- ALWAYS validate with pubky-app-specs WASM before writing
- ALWAYS use the correct namespace (eventky.app for events/calendars/attendees)
- NEVER write to another user's path
- Timestamps MUST be Unix microseconds for dtstamp/created/last_modified
- After writing, invalidate relevant TanStack Query caches

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/gillohner) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->