@sdxc/activitypub 0.0.0-pre.1

package/dist/lib/stringify.d.ts

@@ -0,0 +1,51 @@
+import type { ActivityPub } from "./types.js";
+/**
+ * The extension terms this package writes, defined the way Mastodon defines them, so a
+ * JSON-LD processor on the other side expands each to the IRI its own writer uses.
+ */
+export declare const EXTENSION_CONTEXT: {
+    readonly manuallyApprovesFollowers: "as:manuallyApprovesFollowers";
+    readonly sensitive: "as:sensitive";
+    readonly Hashtag: "as:Hashtag";
+    readonly alsoKnownAs: {
+        readonly "@id": "as:alsoKnownAs";
+        readonly "@type": "@id";
+    };
+    readonly movedTo: {
+        readonly "@id": "as:movedTo";
+        readonly "@type": "@id";
+    };
+    readonly toot: "http://joinmastodon.org/ns#";
+    readonly featured: {
+        readonly "@id": "toot:featured";
+        readonly "@type": "@id";
+    };
+    readonly discoverable: "toot:discoverable";
+    readonly indexable: "toot:indexable";
+    readonly Emoji: "toot:Emoji";
+    readonly blurhash: "toot:blurhash";
+    readonly focalPoint: {
+        readonly "@container": "@list";
+        readonly "@id": "toot:focalPoint";
+    };
+    readonly schema: "http://schema.org#";
+    readonly PropertyValue: "schema:PropertyValue";
+    readonly value: "schema:value";
+    readonly misskey: "https://misskey-hub.net/ns#";
+    readonly _misskey_quote: "misskey:_misskey_quote";
+    readonly quote: {
+        readonly "@id": "https://w3id.org/fep/044f#quote";
+        readonly "@type": "@id";
+    };
+    readonly quoteUri: "http://fedibird.com/ns#quoteUri";
+};
+/**
+ * Writes a document as JSON text with its `@context`, ready to serve or deliver. It
+ * omits `null`, empty arrays and empty maps, never writes `bto` or `bcc`, and writes
+ * dates as ISO 8601; embedded objects carry no `@context` of their own.
+ *
+ * @param document - Any document, parsed or authored.
+ * @example
+ * stringify({ id: NOTE_ID, type: "Note", attributedTo: [ACTOR_ID], to: [PUBLIC], content: html });
+ */
+export declare function stringify(document: ActivityPub.Draft<ActivityPub.Document>): string;

package/dist/lib/stringify.js

@@ -0,0 +1,122 @@
+import { isObject } from "./compact.js";
+import { AS2_CONTEXT, DATA_INTEGRITY_CONTEXT, MULTIKEY_CONTEXT, SECURITY_CONTEXT, } from "./constants.js";
+/**
+ * The extension terms this package writes, defined the way Mastodon defines them, so a
+ * JSON-LD processor on the other side expands each to the IRI its own writer uses.
+ */
+export const EXTENSION_CONTEXT = {
+    manuallyApprovesFollowers: "as:manuallyApprovesFollowers",
+    sensitive: "as:sensitive",
+    Hashtag: "as:Hashtag",
+    alsoKnownAs: { "@id": "as:alsoKnownAs", "@type": "@id" },
+    movedTo: { "@id": "as:movedTo", "@type": "@id" },
+    toot: "http://joinmastodon.org/ns#",
+    featured: { "@id": "toot:featured", "@type": "@id" },
+    discoverable: "toot:discoverable",
+    indexable: "toot:indexable",
+    Emoji: "toot:Emoji",
+    blurhash: "toot:blurhash",
+    focalPoint: { "@container": "@list", "@id": "toot:focalPoint" },
+    schema: "http://schema.org#",
+    PropertyValue: "schema:PropertyValue",
+    value: "schema:value",
+    misskey: "https://misskey-hub.net/ns#",
+    _misskey_quote: "misskey:_misskey_quote",
+    quote: { "@id": "https://w3id.org/fep/044f#quote", "@type": "@id" },
+    quoteUri: "http://fedibird.com/ns#quoteUri",
+};
+/** Members never written: ActivityPub §6 strips blind recipients before delivery. */
+const STRIPPED_MEMBERS = new Set(["bto", "bcc"]);
+/**
+ * Whether a written value carries nothing, which `stringify` omits rather than writing
+ * `null`, `[]` or `{}`.
+ *
+ * @param value - A value already written.
+ */
+function isEmpty(value) {
+    if (value === undefined || value === null)
+        return true;
+    if (Array.isArray(value))
+        return value.length === 0;
+    return isObject(value) && Object.keys(value).length === 0;
+}
+/**
+ * A value as JSON: dates as ISO 8601, arrays and embedded objects written member by
+ * member with empty ones dropped.
+ *
+ * @param value - Any member of a document.
+ */
+function writeValue(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.map(writeValue).filter((entry) => !isEmpty(entry));
+    if (isObject(value))
+        return writeMembers(value);
+    return value;
+}
+/**
+ * An object's members as JSON, `id` and `type` first. `quote` is also written as
+ * `_misskey_quote` and `quoteUri`, which Misskey and older Fedibird-derived servers read.
+ *
+ * @param document - The object, as the API shapes it.
+ */
+function writeMembers(document) {
+    let output = {};
+    if (document.id !== undefined)
+        output.id = document.id;
+    if (document.type !== undefined)
+        output.type = document.type;
+    for (let [member, value] of Object.entries(document)) {
+        if (member === "id" || member === "type" || STRIPPED_MEMBERS.has(member))
+            continue;
+        let written = writeValue(value);
+        if (isEmpty(written))
+            continue;
+        output[member] = written;
+        if (member === "quote") {
+            output._misskey_quote = written;
+            output.quoteUri = written;
+        }
+    }
+    return output;
+}
+/**
+ * Whether a member of a document holds at least one entry.
+ *
+ * @param document - The document.
+ * @param member - The member name.
+ */
+function hasEntries(document, member) {
+    let value = document[member];
+    return Array.isArray(value) ? value.length > 0 : value !== undefined && value !== null;
+}
+/**
+ * The `@context` a document is written with: AS2, the security vocabulary, the
+ * data-integrity and Multikey contexts only when the document uses them, then the
+ * extension terms.
+ *
+ * @param document - The document being written.
+ */
+function contextFor(document) {
+    let context = [AS2_CONTEXT, SECURITY_CONTEXT];
+    if (hasEntries(document, "proof"))
+        context.push(DATA_INTEGRITY_CONTEXT);
+    if (hasEntries(document, "assertionMethod"))
+        context.push(MULTIKEY_CONTEXT);
+    context.push(EXTENSION_CONTEXT);
+    return context;
+}
+/**
+ * Writes a document as JSON text with its `@context`, ready to serve or deliver. It
+ * omits `null`, empty arrays and empty maps, never writes `bto` or `bcc`, and writes
+ * dates as ISO 8601; embedded objects carry no `@context` of their own.
+ *
+ * @param document - Any document, parsed or authored.
+ * @example
+ * stringify({ id: NOTE_ID, type: "Note", attributedTo: [ACTOR_ID], to: [PUBLIC], content: html });
+ */
+export function stringify(document) {
+    let members = document;
+    return JSON.stringify({ "@context": contextFor(members), ...writeMembers(members) });
+}

package/dist/lib/tombstone.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The document a deleted object is served as, so a server that refetches it learns it
+ * is gone (`respond` answers it with `410`) and a `Delete` names what was removed.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { ActivityPub } from "./types.js";
+/** What a deleted object is described by. */
+export interface TombstoneInit {
+    /** The deleted object's own id, which the Tombstone keeps. */
+    id: string;
+    /** The type the object had, such as `Note` or `Article`. */
+    formerType?: string | null;
+    deleted?: Date | null;
+}
+/**
+ * A `Tombstone` for a deleted object, served in its place and embedded in its `Delete`.
+ *
+ * @param init - The object's id, former type and deletion time.
+ * @example
+ * return respond(tombstone({ id: post.url, formerType: "Article", deleted: post.deletedAt }));
+ */
+export declare function tombstone(init: TombstoneInit): ActivityPub.Tombstone;

package/dist/lib/tombstone.js

@@ -0,0 +1,15 @@
+/**
+ * A `Tombstone` for a deleted object, served in its place and embedded in its `Delete`.
+ *
+ * @param init - The object's id, former type and deletion time.
+ * @example
+ * return respond(tombstone({ id: post.url, formerType: "Article", deleted: post.deletedAt }));
+ */
+export function tombstone(init) {
+    return {
+        id: init.id,
+        type: "Tombstone",
+        formerType: init.formerType ?? null,
+        deleted: init.deleted ?? null,
+    };
+}

package/dist/lib/types.d.ts

@@ -0,0 +1,249 @@
+/**
+ * The ActivityStreams 2.0 vocabulary as this package reads and writes it: every member
+ * normalized to one shape whatever the sender chose, so a handler never branches on
+ * whether a value arrived as a string, an array or an embedded object.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { ACTIVITY_TYPES, ACTOR_TYPES } from "./constants.js";
+export declare namespace ActivityPub {
+    /** An IRI or the object it names; which one arrives is the sender's choice. */
+    type Ref<T> = string | T;
+    /**
+     * A document as an app authors it for `stringify` and `respond`: `id` and `type` are
+     * required and every other member may be left out, which writes as absent.
+     *
+     * @template T - The full shape, as `parse*` returns it.
+     */
+    type Draft<T> = T extends Date ? T : T extends string | number | boolean | null | undefined ? T : T extends readonly unknown[] ? {
+        [K in keyof T]: Draft<T[K]>;
+    } : T extends object ? {
+        [K in keyof T as K extends "id" | "type" ? K : never]: Draft<T[K]>;
+    } & {
+        [K in keyof T as K extends "id" | "type" ? never : K]?: Draft<T[K]>;
+    } : T;
+    /** The ActivityStreams activity types this package names. */
+    type ActivityType = (typeof ACTIVITY_TYPES)[number];
+    /** The ActivityStreams actor types. */
+    type ActorType = (typeof ACTOR_TYPES)[number];
+    /**
+     * Any ActivityStreams object. A type this package does not model (`Note`, `Article`,
+     * `Question`, `Event`, or an extension) keeps its `type`, so an app ignores it on purpose.
+     */
+    interface Object {
+        /** An absolute IRI; the origin every ownership check compares against. */
+        id: string;
+        /** The first type a sender listed that this package knows, else the first it listed. */
+        type: string;
+        /** Always IRIs; an embedded author is never trusted over the author's own document. */
+        attributedTo: string[];
+        /** Addressing, with every spelling of the public collection read as `PUBLIC`. */
+        to: string[];
+        cc: string[];
+        /** Read for fan-out, and never written: ActivityPub §6 strips them before delivery. */
+        bto: string[];
+        bcc: string[];
+        /** Filled from `nameMap` when a sender sent only the map. */
+        name: string | null;
+        /** Language tag to text; empty when the sender sent only the plain value. */
+        nameMap: Record<string, string>;
+        /** A content warning on a sensitive Note; the lede of an Article. */
+        summary: string | null;
+        summaryMap: Record<string, string>;
+        /** HTML, unsanitized; filled from `contentMap` when a sender sent only the map. */
+        content: string | null;
+        contentMap: Record<string, string>;
+        /** The page a person opens: the first `text/html` link a sender gave, else the first link. */
+        url: string | null;
+        inReplyTo: string | null;
+        /** The quoted object, from `quote`, `quoteUrl`, `quoteUri` or `_misskey_quote`. */
+        quote: string | null;
+        published: Date | null;
+        updated: Date | null;
+        /** Mastodon reads `summary` on a sensitive Note as a content warning. */
+        sensitive: boolean;
+        tag: Tag[];
+        attachment: Attachment[];
+        /** FEP-8b32 proofs, kept so a verifier can find them; an empty list writes no proof. */
+        proof: Proof[];
+    }
+    /** An activity: someone (`actor`) doing something (`type`) to something (`object`). */
+    interface Activity extends Object {
+        type: ActivityType | (string & {});
+        /** Always an IRI. An embedded actor is never trusted over the actor's own document. */
+        actor: string;
+        /**
+         * Embedded objects are kept, because Create carries its Note and Accept or Undo the
+         * Follow they answer. Trust one only when its `id` has the actor's origin.
+         */
+        object: Ref<Object | Activity> | null;
+        target: string | null;
+    }
+    /** An account that can follow, be followed, and send or receive activities. */
+    interface Actor extends Object {
+        type: ActorType;
+        /** The `user` of `acct:user@host`; Mastodon resolves it back through WebFinger. */
+        preferredUsername: string;
+        inbox: string;
+        outbox: string | null;
+        followers: string | null;
+        following: string | null;
+        /** Pinned posts, a Mastodon extension. */
+        featured: string | null;
+        endpoints: Endpoints;
+        /** The RSA key HTTP signatures from this actor verify against. */
+        publicKey: PublicKey | null;
+        /** FEP-521a Multikey entries; carries the Ed25519 key FEP-8b32 proofs name. */
+        assertionMethod: Multikey[];
+        alsoKnownAs: string[];
+        movedTo: string | null;
+        manuallyApprovesFollowers: boolean;
+        discoverable: boolean;
+        indexable: boolean;
+        icon: Image | null;
+        image: Image | null;
+    }
+    /** Server-wide endpoints of an actor. */
+    interface Endpoints {
+        /** Preferred for delivery, so one POST reaches every follower on that server. */
+        sharedInbox: string | null;
+    }
+    /** An actor's RSA public key, in the shape Mastodon publishes and reads. */
+    interface PublicKey {
+        /** `<actor>#main-key` on Mastodon; the `keyId` HTTP signatures name. */
+        id: string;
+        /** The actor the key belongs to; a key whose owner differs never verifies that actor. */
+        owner: string;
+        publicKeyPem: string;
+    }
+    /** A FEP-521a verification method. */
+    interface Multikey {
+        id: string;
+        type: "Multikey";
+        controller: string;
+        /** The key in multibase, `z` + base58btc for Ed25519. */
+        publicKeyMultibase: string;
+    }
+    /** An FEP-8b32 object integrity proof. */
+    interface Proof {
+        type: "DataIntegrityProof";
+        cryptosuite: string;
+        /** The `Multikey` id that signed, under the signer's actor. */
+        verificationMethod: string;
+        proofPurpose: string;
+        proofValue: string;
+        created: Date | null;
+    }
+    /** An entry of `tag`: a hashtag, a mention, or a custom emoji. */
+    type Tag = Hashtag | Mention | Emoji;
+    /** A topic; Mastodon lists the object on that tag's timeline. */
+    interface Hashtag {
+        type: "Hashtag";
+        /** With its `#`, as Mastodon writes it. */
+        name: string;
+        href: string | null;
+    }
+    /** An actor the object names, which Mastodon notifies and links in the rendered text. */
+    interface Mention {
+        type: "Mention";
+        /** The mentioned actor's id. */
+        href: string;
+        /** `@user@host` as the sender wrote it. */
+        name: string | null;
+    }
+    /** A custom emoji, which `content` names as `:shortcode:`. */
+    interface Emoji {
+        type: "Emoji";
+        id: string | null;
+        /** The shortcode with its colons, `:blobcat:`. */
+        name: string;
+        icon: Image;
+        updated: Date | null;
+    }
+    /** An entry of `attachment`: a media file, or a profile field. */
+    type Attachment = Media | PropertyValue;
+    /** An attached file. Mastodon sends `Document`; Pixelfed and Misskey also send `Image`. */
+    interface Media {
+        type: "Document" | "Image" | "Video" | "Audio";
+        url: string;
+        mediaType: string | null;
+        /** The alt text. */
+        name: string | null;
+        blurhash: string | null;
+        width: number | null;
+        height: number | null;
+        /** Mastodon's crop point, each coordinate from -1 to 1. */
+        focalPoint: [number, number] | null;
+    }
+    /** A profile metadata field, as Mastodon lists them in an actor's `attachment`. */
+    interface PropertyValue {
+        type: "PropertyValue";
+        name: string;
+        /** HTML; a verified link is an `<a rel="me">`. */
+        value: string;
+    }
+    /** An avatar, header or emoji image. */
+    interface Image {
+        type: "Image";
+        url: string;
+        mediaType: string | null;
+    }
+    /**
+     * What a deleted object is served as, answered with `410`. `parseObject` reads one as an
+     * `Object` whose `type` is `Tombstone`.
+     */
+    interface Tombstone {
+        id: string;
+        type: "Tombstone";
+        formerType: string | null;
+        deleted: Date | null;
+    }
+    /** An entry of a collection: an IRI, or the activity or object itself. */
+    type Item = Ref<Object | Activity>;
+    /** An unordered collection, such as Mastodon's `replies`. */
+    interface Collection {
+        id: string;
+        type: "Collection";
+        totalItems: number | null;
+        first: Ref<CollectionPage | OrderedCollectionPage> | null;
+        last: string | null;
+        items: Item[];
+    }
+    /** One page of an unordered collection. */
+    interface CollectionPage {
+        /** `null` for a page embedded without one, as Mastodon embeds the first page of `replies`. */
+        id: string | null;
+        type: "CollectionPage";
+        partOf: string | null;
+        next: string | null;
+        prev: string | null;
+        totalItems: number | null;
+        items: Item[];
+    }
+    /** A collection in reverse chronological order: outbox, followers, following, featured. */
+    interface OrderedCollection {
+        id: string;
+        type: "OrderedCollection";
+        /** Alone, with no `first`, it is Mastodon's "hide network" shape of a followers list. */
+        totalItems: number | null;
+        first: Ref<CollectionPage | OrderedCollectionPage> | null;
+        last: string | null;
+        orderedItems: Item[];
+    }
+    /** One page of an ordered collection. */
+    interface OrderedCollectionPage {
+        /** `null` for a page embedded without one. */
+        id: string | null;
+        type: "OrderedCollectionPage";
+        partOf: string | null;
+        next: string | null;
+        prev: string | null;
+        totalItems: number | null;
+        orderedItems: Item[];
+    }
+    /** Any of the four collection shapes `parseCollection` reads. */
+    type AnyCollection = Collection | CollectionPage | OrderedCollection | OrderedCollectionPage;
+    /** Any document `stringify` and `respond` write. */
+    type Document = Object | Activity | Actor | Tombstone | AnyCollection;
+}

package/dist/memory.d.ts

@@ -0,0 +1,77 @@
+/**
+ * In-memory implementations of every store the package calls, for tests and for a local
+ * server that needs no persistence. They pass the conformance suite, so a test that runs
+ * against them exercises the same contracts a production store is held to.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { DurationInput } from "@sdxc/duration";
+import type { Result } from "@sdxc/result";
+import type { ActorKeys } from "./keys.js";
+import type { ActivityPub } from "./lib/types.js";
+import type { Follower, FollowerStore, KeyProvider, LocalObjects, SeenActivities, StorePage } from "./store.js";
+/**
+ * Followers held in insertion order, so every listing is stable across pages. A repeated `put`
+ * keeps the follower's position, and every read returns a copy the caller may change freely.
+ */
+export declare class MemoryFollowerStore implements FollowerStore {
+    #private;
+    /** @param followers Followers the store starts with, as if each had been `put` in order. */
+    constructor(followers?: Follower[]);
+    /** Inserts or replaces by `(actor, id)`, refreshing inbox, shared inbox, `followId` and state. */
+    put(follower: Follower): Promise<Result<void, Error>>;
+    /** The follower in either state, or `null` when `id` does not follow `actor`. */
+    get(actor: string, id: string): Promise<Result<Follower | null, Error>>;
+    /** Succeeds whether or not the follower existed. */
+    remove(actor: string, id: string): Promise<Result<void, Error>>;
+    /** Drops followers of every local actor whose inbox or shared inbox is `inbox`. */
+    removeInbox(inbox: string): Promise<Result<void, Error>>;
+    /** Accepted followers of `actor` in insertion order, narrowed to `origin` when given. */
+    list(actor: string, options: {
+        cursor: string | null;
+        limit: number;
+        origin?: string;
+    }): Promise<Result<StorePage<Follower>, Error>>;
+    /** Accepted followers of `actor`, the number the followers collection publishes. */
+    count(actor: string): Promise<Result<number, Error>>;
+    /** Each distinct `sharedInbox ?? inbox` once, in the order its first follower was added. */
+    inboxes(actor: string, options: {
+        cursor: string | null;
+        limit: number;
+    }): Promise<Result<StorePage<string>, Error>>;
+}
+/** What a `MemorySeenActivities` reads the time from. */
+export interface MemorySeenActivitiesOptions {
+    /**
+     * Milliseconds since the epoch, read on every claim, which is what lets a test pass a TTL
+     * without waiting for it.
+     *
+     * @default Date.now
+     */
+    now?: () => number;
+}
+/** Claimed activity ids, each held until its TTL passes and then claimable again. */
+export declare class MemorySeenActivities implements SeenActivities {
+    #private;
+    /** @param options The clock claims are timed against. */
+    constructor(options?: MemorySeenActivitiesOptions);
+    /** Fails on a TTL `@sdxc/duration` cannot read, so a mistyped TTL surfaces as an error. */
+    claim(id: string, ttl: DurationInput): Promise<Result<boolean, Error>>;
+}
+/** A fixed set of objects the app serves, found by their `id`. */
+export declare class MemoryLocalObjects implements LocalObjects {
+    #private;
+    /** @param objects The objects served; a later one with a repeated `id` wins. */
+    constructor(objects?: ActivityPub.Object[]);
+    /** The object served under `id`, or `null` for any other IRI. */
+    find(id: string): Promise<Result<ActivityPub.Object | null, Error>>;
+}
+/** A fixed set of hosted actors' keys, found by actor id. */
+export declare class MemoryKeyProvider implements KeyProvider {
+    #private;
+    /** @param keys The keys of every hosted actor; a later entry for the same actor wins. */
+    constructor(keys?: ActorKeys[]);
+    /** The actor's keys, or `null` for an actor this provider does not host. */
+    keysOf(actor: string): Promise<Result<ActorKeys | null, Error>>;
+}