server/packages/sdk

@versia/sdk

Federation types, validators and cryptography for Versia server implementations.

Usage

Entities

The @versia/sdk/entities module provides TypeScript classes for working with Versia entities. These classes provide type-safe access to entity properties and methods for serialization/deserialization.

import { Note, User } from "@versia/sdk/entities";

const note = new Note({
    id: "00000000-0000-0000-0000-000000000000",
    type: "Note",
});

// You can also parse from JSON, which will apply the schema validation
const invalidJson = {
    id: "00000000-0000-0000-0000-000000000000",
    invalid: "property",
};

// Will throw an error
const invalidNote = await Note.fromJSON(invalidJson);

const validJson = {
    id: "00000000-0000-0000-0000-000000000000",
    type: "Note",
};

const validNote = await Note.fromJSON(validJson);

Some entities like Note have additional properties, like content or attachments, which are automatically calculated from the relevant properties.

import { TextContentFormat, Note } from "@versia/sdk/entities";

const note = new Note({
    id: "00000000-0000-0000-0000-000000000000",
    type: "Note",
    content: {
        "text/plain": {
            content: "Hello, world!",
            remote: false,
        },
    },
});

const content = note.content;
// Is equivalent to
const content = new TextContentFormat(note.data.content);

Schemas

Additionally, the Zod schemas used for validation are available in the @versia/sdk/schemas module. You can use these to directly validate incoming data, without using the entity classes.

import { NoteSchema, UserSchema } from "@versia/sdk/schemas";

const response = await fetch("https://example.com/notes/123");
const json = await response.json();

const noteSchema = NoteSchema.parse(json);

Sorter

The @versia/sdk/sorter module provides a class for inbox request handling. It allows you to automatically sort and process incoming entities based on their type.

import { EntitySorter } from "@versia/sdk";
import { Note, User } from "@versia/sdk/entities";

app.post("/inbox", async (req, res) => {
    const json = await req.json();

    const sorter = new EntitySorter(json);

    await sorter
        .on(Note, (note) => {
            console.log(note);
        })
        .on(User, (user) => {
            console.log(user);
        })
        .sort();
});

Cryptography

The @versia/sdk/crypto module provides functions for signing and verifying requests using the Ed25519 algorithm.

import { sign, verify } from "@versia/sdk/crypto";

const keys = await crypto.subtle.generateKey("Ed25519", true, [
    "sign",
    "verify",
]);

// URI of the User that is signing the request
const authorUrl = new URL("https://example.com");

const req = new Request("https://example.com/notes/123", {
    method: "POST",
    body: JSON.stringify({
        id: "00000000-0000-0000-0000-000000000000",
        type: "Note",
    }),
});

const signedReq = await sign(keys.privateKey, authorUrl, req);

const verified = await verify(keys.publicKey, signedReq);

Prerequisites

For Usage

See the Compatibility section for the supported environments. Any package manager can be used to install the packages.

For Development

• Bun version 1.1.8 or higher.
• Either the Linux or macOS operating systems. (Windows will work, but is not officially supported.)

Compatibility

This library is built for JavaScript runtimes with the support for:

• ES Modules
• ECMAScript 2020
• (only required for cryptography) Ed25519 cryptography in the WebCrypto API

Runtimes

• Node.js: 14.0+ is the minimum (18.0+ for cryptography), but only Node.js 20.0+ (LTS) is officially supported.
• Deno: Support is unknown. 1.0+ is expected to work.
• Bun: Bun 1.1.8 is the minimum-supported version. As Bun is rapidly evolving, this may change. Previous versions may also work.

Browsers

Consequently, this library is compatible without any bundling in the following browser versions:

• Chrome: 80+
• Edge: 80+
• Firefox: 74+
• Safari: 13.1+
• Opera: 67+
• Internet Explorer: None

Cryptography functions are supported in the following browsers:

• Safari: 17.0+
• Firefox: 129.0+
• Chrome: 113.0+ with #enable-experimental-web-platform-features enabled

If you are targeting older browsers, please don't, you are doing yourself a disservice.

Transpilation to non-ES Module environments is not officially supported, but should be simple with the use of a bundler like Parcel or Rollup.

Installation

Package is distributed as a scoped package on the NPM registry and JSR.

We strongly recommend using JSR over NPM for all your packages that are available on it.

# NPM version
deno add npm:@versia/sdk # For Deno
npm install @versia/sdk # For NPM
yarn add @versia/sdk # For Yarn
pnpm add @versia/sdk # For PNPM
bun add @versia/sdk # For Bun

# JSR version
deno add @versia/sdk # For Deno
npx jsr add @versia/sdk # For JSR
yarn dlx jsr add @versia/sdk # For Yarn
pnpm dlx jsr add @versia/sdk # For PNPM
bunx jsr add @versia/sdk # For Bun

From Source

If you want to install from source, you can clone this repository and run the following commands:

bun install # Install dependencies

bun run build # Build the packages

The built package will be in the sdk/dist folder.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Projects

• Bun: Thanks to the Bun team for creating an amazing JavaScript runtime.
• TypeScript: TypeScript is the backbone of this project.
• Node.js: Node.js created the idea of JavaScript on the server.

People

• April John: Creator and maintainer of the Versia Server ActivityPub bridge.