SDK
The SDK is the TypeScript package @seed-hypermedia/client, and this page shows how to install it, read documents, and build, sign and publish your own.

The SDK is the TypeScript package @seed-hypermedia/client. It reads documents, builds and signs new ones, and publishes them. The Seed app, the Seed web app, the Seed CLI, the vault and Seed Agents all use this same package, so what works here works in all of them.

The package knows how to encode and sign a blob, how to build a document change, how to turn a document into markdown and back, and how to look up a schema. It does not need React or a daemon. It only needs fetch, so it runs in Node, Bun, browsers and React Native.

This page is the reference. If you have never published anything, start with Getting started. If you only need to read public data, the Seed API over plain HTTP may be enough.

Install and import

npm install @seed-hypermedia/client zod@^4.6.6

Fact

Value

Package

@seed-hypermedia/client on npm, ESM only

Peer dependencies

zod ^4.6.6 (required), pdfjs-dist (optional, only for pdfToBlocks)

Entry points

the root barrel, plus every module as a subpath: @seed-hypermedia/client/<module>

Runtime requirements

fetch; WebCrypto only for the browser sign-in module

Versioning

CI publishes a new patch on every push to main that touches the package, so the npm version is always ahead of the repository's package.json. Pin the version you tested against

The root barrel exports the client, the blob builders, the markdown dialect, the id helpers and the document-state helpers. Some modules are not in the root barrel. You import them by their subpath: auth (browser sign-in), hmauth (the sign-in protocol), blobs (key pairs, profiles, low-level capability and signing primitives), signed-blob (user-defined signed blobs), hm-types (the zod schemas of every type), explore-query (the query grammar), schema-engine and schema-resolve (Hypermedia Schemas), vault-local, cbor, dag-json, base64. keyfile has a subpath and is also exported from the root as keyfile.

import {createSeedClient, createDocumentBlobs, unpackHmId} from '@seed-hypermedia/client' import {HMDocumentSchema} from '@seed-hypermedia/client/hm-types' import * as blobs from '@seed-hypermedia/client/blobs'

The client

createSeedClient(baseUrl: string, options?: {fetch?, headers?}): SeedClient type SeedClient = { baseUrl: string request<K extends HMRequest['key']>(key: K, input, options?: {signal?: AbortSignal}): Promise<output> publish(input: {blobs: {cid?: string; data: Uint8Array}[]}): Promise<{cids: string[]}> publishBlobs: same as publish putBlob(blob: {cid: string; data: Uint8Array}, options?: {signal?: AbortSignal}): Promise<void> // one blob through POST /ipfs/<cid> daemonBlobCid(data: Uint8Array): string // the CID the daemon gives a DAG-CBOR blob published without one publishDocument(input: PublishDocumentInput, signer: AnySigner): Promise<{version, genesis, generation}> }

baseUrl is the address of any Seed web server: https://hyper.media, your own site, or the desktop app's local bridge (http://localhost:56004 in the installed app, 58004 in a dev build). The client speaks the Seed API at /api/<Key>. It never talks to the daemon's gRPC port.

request(key, input) validates the input against the zod schema for that key, sends it, and validates the output. Read keys go out as GET /api/<Key>?…. The five action keys (PublishBlobs, PrepareDocumentChange, QueryDocuments, ListDocumentAttributeNames, ListDocumentAttributeValues) go out as POST /api/<Key> with a DAG-CBOR body. The client unwraps every response for you. Three keys (QueryDocuments and the two attribute listings) return the daemon's own JSON, so their field names follow the proto files.

Some sites limit the size of an API body. When a site refuses a publish body as too large (413), the client sends the blobs one by one with putBlob.

headers can be an object or a function returning one, which is how you attach Authorization: Bearer <token> for private reads. Errors are typed: SeedValidationError (bad input or unknown key), SeedNetworkError (fetch itself failed) and SeedClientError (a non-2xx status, with the server's error text folded into the message and the status and body kept on the error).

Identity and signing

Everything you publish is signed by an Ed25519 key. The SDK does not care where that key lives. It needs a signer:

type HMSigner = {getPublicKey(): Promise<Uint8Array>; sign(data: Uint8Array): Promise<Uint8Array>} type PrincipalSigner = {readonly principal: Uint8Array; sign(data: Uint8Array): Promise<Uint8Array>} type AnySigner = HMSigner | PrincipalSigner // every builder accepts either

getPublicKey returns the 34-byte principal: the bytes 0xed 0x01 followed by the 32-byte public key. Encoded as base58btc it is the z6Mk… account id. toHMSigner and toPrincipalSigner convert between the two shapes.

Ways to get a signer:

    Generate a key with generateNobleKeyPair() from the blobs module, or rebuild one from a 32-byte seed with nobleKeyPairFromSeed(seed). A NobleKeyPair is a PrincipalSigner.

    Load a .hmkey.json file exported by the Seed app or seed-cli key export: keyfile.load(json, password?) returns {payload, seed, publicKey}. Pass the seed to nobleKeyPairFromSeed. See Keys for the file format.

    Read a local vault of the desktop app or daemon with loadLocalVaultAccounts({path?, dev?}) from vault-local. It is read-only and decrypts the vault with the secret from the OS keychain or the SEED_VAULT_KEK variable.

    A browser session key delegated by the user's vault: createSessionSigner(session) from the auth module. See Sign in with Seed.

Mnemonic derivation (BIP-39 words to a key) is not in the SDK. The Seed CLI and the apps do it with SLIP-10 at path m/44'/104109'/0'. Keys has the details.

Principal helpers live in blobs: principalFromEd25519(raw32), principalToString(p), principalFromString(s), principalEqual(a, b).

Reading

Ids first. unpackHmId('hm://<uid>/<path>?v=<version>#<block>') returns an UnpackedHypermediaId with uid, path (an array or null), version, blockRef, blockRange and latest. packHmId reverses it. See URLs for the id grammar. resolveHypermediaUrl(url) turns a web URL into an id by asking the site with an OPTIONS request and reading its X-Hypermedia-* headers. resolveId accepts either form. resolveIdWithClient(rawId, {client?, serverUrl?}) also returns a client for the URL's own origin, which is why a web URL argument to the CLI ignores --server.

const client = createSeedClient('https://hyper.media') const id = unpackHmId('hm://z6Mko5npVz4Bx9Rf4vkRUf2swvb568SDbhLwStaha3HzgrLS/resources/self-host-seed')! const resource = await client.request('Resource', id) if (resource.type === 'document') console.log(resource.document.metadata.name)

The id must name an account by its z6Mk… id. The Seed API does not resolve a domain name inside an hm:// URL. Every key, with its input and output, is in the Seed API key tables. Inputs that the tables show as an hm:// string are an unpacked id here.

HMResource is a union on type: document, comment, redirect (with redirectTarget and republish), not-found, tombstone, error. HMDocument carries content (a tree of {block, children?}), metadata, version, genesis, authors, generationInfo and visibility.

To follow moves and republishes, followRedirects(client, id) walks the redirect chain, followToDocument stops at the first document, and resolveEditableDocument returns what an editor should load together with the address that a new change must take over.

Writing documents

A document is a DAG of signed Change blobs plus a Ref that names the current heads. Documents explains the model. The SDK gives you the operations, the builders and one rule you must not break.

type DocumentOperation = | {type: 'SetAttributes'; attrs: {key: string[]; value: string | number | boolean | null}[]} | {type: 'ReplaceBlock'; block: unknown} | {type: 'MoveBlocks'; blocks: string[]; parent: string} | {type: 'DeleteBlocks'; blocks: string[]}

Create a document. createDocumentBlobs(signer, {space, path, ops, capability?, generation?, visibility?}) returns {blobs, genesis, version, ts} ready for client.publish. space is the account id of the space you write into. path is '' for the account's home document and /a/b otherwise.

const {blobs} = await createDocumentBlobs(signer, { space: myUid, path: '/notes/first', ops: [ {type: 'SetAttributes', attrs: [{key: ['name'], value: 'First note'}]}, {type: 'ReplaceBlock', block: {id: 'b1', type: 'Paragraph', text: 'Hello.', annotations: []}}, {type: 'MoveBlocks', blocks: ['b1'], parent: ''}, ], }) await client.publish({blobs})

The genesis rule. A document's identity is its genesis Change, and only a home document (path '') has a deterministic one. Documents has the rule. createDocumentBlobs applies it for you: an ordinary document's first content Change is its genesis, and a home document starts from createHomeGenesisChange. createGenesisChange is the older name of that function. Only the owner can create a home. The builder refuses any other signer for path ''.

Update a document. Fetch the current state, build a Change on the heads, and publish it with a fresh Ref:

const state = await resolveDocumentState(client, 'hm://' + myUid + '/notes/first') const {unsignedBytes, ts} = createChangeOps({ ops, genesisCid: CID.parse(state.genesis), deps: state.heads.map((h) => CID.parse(h)), depth: state.headDepth + 1, }) const change = await createChange(unsignedBytes, signer) const ref = await createVersionRef( {space: myUid, path: '/notes/first', genesis: state.genesis, version: change.cid.toString(), generation: Number(ts)}, signer, ) await client.publish({blobs: [{data: change.bytes, cid: change.cid.toString()}, ...ref.blobs]})

resolveDocumentState walks ListChanges to find the genesis, the heads and the head depth (depth is not in the read API, so it is recomputed). createChangeOps builds the unsigned CBOR. createChange signs it and returns {bytes, cid, genesis, ts}. Concurrent heads merge by listing several deps.

Let the server build the ops. client.publishDocument({account, path?, changes, baseVersion?, genesis?, generation?, capability?, visibility?}, signer) takes proto-style changes (the shape the app's editor produces), asks the site's PrepareDocumentChange to compute the CRDT ops, signs the result with signDocumentChange and publishes. It also bootstraps a brand-new home document client-side. The Seed web app uses this path. Scripts that already have block-level ops can stay with the builders above.

Refs. createVersionRef points a path at a version (this is also a fork: a new path on an existing genesis). createTombstoneRef({space, path, genesis, generation, capability?}) deletes. createRedirectRef({space, path, genesis, generation, targetSpace?, targetPath, republish?}) moves a path elsewhere, and with republish: true shows the target's content in place. A Ref with a higher generation supersedes the one at the path, so a takeover mints Date.now().

Writing into someone else's space. Pass capability: <cid> on every Change-carrying Ref, tombstone and redirect. A capability is what lets your key write there. resolveCapability(client, targetAccount, signerAccount, path?) finds a WRITER or AGENT capability the space published for your key. It returns the capability's CID. It returns undefined when you are the owner, and also when no capability was found, so check for that before you publish into someone else's space. See Permissions.

The CID rule. A blob that another blob references by CID must be published with its cid set. Blobs has the rule and the two hashes behind it. The builders fill cid for you. Keep it when you assemble your own publish payload.

Comments, contacts, profiles, capabilities

These are snapshot blobs, replaced whole on edit and addressed as <author>/<tsid>. See Comments, contacts and capabilities, and Identity for profiles.

createComment({docId, docVersion, content: HMBlockNode[], replyCommentVersion?, rootReplyCommentVersion?, quoting?, visibility?}, signer) updateComment({commentId, targetAccount, targetPath, targetVersion, content, replyParentVersion?, rootReplyCommentVersion?}, signer) deleteComment({commentId, targetAccount, targetPath, targetVersion}, signer) commentRecordIdFromBlob(bytes) // "<author>/<tsid>" createContact({subjectUid, accountUid?, name?, subscribe?}, signer) // → publish input + recordId updateContact(...) deleteContact(...) contactRecordIdFromBlob(...) createCapability({delegateUid, role: 'WRITER' | 'AGENT', path?, label?}, signer) resolveCapability(client, targetAccount, signerAccount, path?) blobs.createProfile(signer, {name, avatar?, description?}, ts) // Encoded<Profile> blobs.createProfileAlias(...)

A comment pins the target docVersion it was written against. quoting: {blockId, range?} makes a block comment: the content is wrapped in an Embed of that block at that version. Replies carry the parent comment's version and the thread root's version. docId is an UnpackedHypermediaId.

Files and media

fileToIpfsBlobs(bytes) chunks a file into UnixFS blocks and returns the blocks plus the root CID, so an image becomes ipfs://<cid> in a block's link or in metadata.icon. filesToIpfsBlobs does several at once. resolveFileLinksInBlocks replaces file:// links in a block tree with published ipfs:// links, and hasFileLinks tells you whether there is anything to upload. Publish the file blocks in the same publish call as the document that links them, or the gateway will report them as not public. Files has the rules.

Markdown

blocksToMarkdown(doc) and parseMarkdown(md) convert between a document and its lossless markdown form, and documentToResolvedMarkdown produces markdown for display. The format and every function around it are on the markdown dialect page.

Typed documents and your own blobs

The Hypermedia Schemas library ships inside the package. schema-engine bundles every schema and its published CID (HM_SCHEMAS, HM_SCHEMA_MANIFEST) and validates values offline: load(ref), validate(value, schema, registry), structFields, requiredFieldNames, resolveSchema. schema-resolve does the parts that need a client: resolveSchemaRef(client, ref) for a CID, a library URL or a type document's URL, effectiveSchemaRef (a document's own attributesSchema, else its parent's childAttributesSchema) and checkDocumentSchema. Hypermedia Schemas explains the model, and Typed documents explains the binding keys.

signed-blob signs any value as a Hypermedia blob: signBlob(signer, body, {typeTag?, ts?}) adds signer, ts and sig, encodes canonical DAG-CBOR and returns {cid, data, ts, signer}. signBlob wants an HMSigner, so wrap a key pair with toHMSigner(keyPair) first. publishSignedBlob(client, signer, body, opts) also publishes, and refuses a type tag that collides with a built-in Seed type. verifySignedBlob(value) checks a signature the way the daemon does. The signing rule is the same everywhere: encode the blob with sig set to 64 zero bytes, sign those bytes, fill sig, encode again, hash with SHA-256. Blobs has the envelope.

Sign in with Seed

The auth module implements the browser half of third-party sign-in: startAuth, handleCallback, getSession, createSessionSigner, clearSession. It is browser-only (WebCrypto Ed25519, IndexedDB, CompressionStream). Sign in with Seed walks through it.

Editor interop

If you are building an editor, hm-types has the zod schemas for every block, annotation and metadata key (HMBlockSchema, HMDocumentSchema, HMRequestSchema, …), and the barrel exports the converters the Seed editor uses: hmBlocksToEditorContent, editorBlocksToHMBlockNodes, hmBlockToEditorBlock, editorBlockToHMBlock. The block-diff module (createBlocksMap, matchBlockIds, computeReplaceOps, rebindTableIdentities) is how the CLI's document update and folder sync turn an edited tree into the minimal set of operations.

Working with it

In the Seed app

The desktop and web apps use this same package. The app is the reference client for what the builders produce.

CLI

Every write in the Seed CLI is one of the builders above followed by client.publish. Read the CLI's source when you want a worked example of a command.

Seed API

The client is a thin layer over the Seed API. Anything the SDK does, you can do with curl and a CBOR encoder.

Agents

Seed Agents call these same functions when an agent's write verb publishes to an hm:// address, signing with server-held identities. Its read verb returns resolved markdown from this package. An external agent that scripts against Seed (a Claude Code session, a bot) should prefer the CLI for one-off commands and this package for anything long-running. See Using Seed from your own agent.

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime