feat(client): ✨ Add client package

.vscode/settings.json

@@ -1,3 +1,3 @@
 {
-    "conventionalCommits.scopes": ["docs", "build", "federation"]
+    "conventionalCommits.scopes": ["docs", "build", "federation", "client"]
 }

client/lysand/base.ts

@@ -0,0 +1,191 @@
+import { DEFAULT_UA } from "./constants";
+
+type HttpVerb = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+type ConvertibleObject = Record<
+    string,
+    string | number | boolean | File | undefined | null
+>;
+
+export interface Output<ReturnType> {
+    data: ReturnType;
+    headers: Headers;
+}
+
+const objectToFormData = (obj: ConvertibleObject): FormData => {
+    return Object.keys(obj).reduce((formData, key) => {
+        if (obj[key] === undefined || obj[key] === null) return formData;
+        formData.append(key, String(obj[key]));
+        return formData;
+    }, new FormData());
+};
+
+export class ResponseError extends Error {}
+
+export class BaseClient {
+    constructor(
+        protected baseUrl: URL,
+        private accessToken?: string,
+    ) {}
+
+    get url(): URL {
+        return this.baseUrl;
+    }
+
+    get token(): string | undefined {
+        return this.accessToken;
+    }
+
+    private async request<ReturnType>(
+        request: Request,
+    ): Promise<Output<ReturnType>> {
+        const result = await fetch(request);
+
+        if (!result.ok) {
+            const error = await result.json();
+            throw new ResponseError(
+                `Request failed (${result.status}): ${
+                    error.error || error.message || result.statusText
+                }`,
+            );
+        }
+
+        return {
+            data: await result.json(),
+            headers: result.headers,
+        };
+    }
+
+    private async constructRequest(
+        path: string,
+        method: HttpVerb,
+        body?: object | FormData,
+        extra?: RequestInit,
+    ): Promise<Request> {
+        return new Request(new URL(path, this.baseUrl).toString(), {
+            method,
+            headers: {
+                Authorization: this.accessToken
+                    ? `Bearer ${this.accessToken}`
+                    : "",
+                "Content-Type": "application/json",
+                "User-Agent": DEFAULT_UA,
+                ...extra?.headers,
+            },
+            body: body
+                ? body instanceof FormData
+                    ? body
+                    : JSON.stringify(body)
+                : undefined,
+            ...extra,
+        });
+    }
+
+    protected async get<ReturnType>(
+        path: string,
+        extra?: RequestInit,
+    ): Promise<Output<ReturnType>> {
+        return await this.request(
+            await this.constructRequest(path, "GET", undefined, extra),
+        );
+    }
+
+    protected async post<ReturnType>(
+        path: string,
+        body?: object,
+        extra?: RequestInit,
+    ): Promise<Output<ReturnType>> {
+        return await this.request(
+            await this.constructRequest(path, "POST", body, extra),
+        );
+    }
+
+    protected async postForm<ReturnType>(
+        path: string,
+        body: FormData | ConvertibleObject,
+        extra?: RequestInit,
+    ): Promise<Output<ReturnType>> {
+        return await this.request(
+            await this.constructRequest(
+                path,
+                "POST",
+                body instanceof FormData ? body : objectToFormData(body),
+                extra,
+            ),
+        );
+    }
+
+    protected async put<ReturnType>(
+        path: string,
+        body?: object,
+        extra?: RequestInit,
+    ): Promise<Output<ReturnType>> {
+        return await this.request(
+            await this.constructRequest(path, "PUT", body, extra),
+        );
+    }
+
+    protected async putForm<ReturnType>(
+        path: string,
+        body: FormData | ConvertibleObject,
+        extra?: RequestInit,
+    ): Promise<Output<ReturnType>> {
+        return await this.request(
+            await this.constructRequest(
+                path,
+                "PUT",
+                body instanceof FormData ? body : objectToFormData(body),
+                extra,
+            ),
+        );
+    }
+
+    protected async patch<ReturnType>(
+        path: string,
+        body?: object,
+        extra?: RequestInit,
+    ): Promise<Output<ReturnType>> {
+        return await this.request(
+            await this.constructRequest(path, "PATCH", body, extra),
+        );
+    }
+
+    protected async patchForm<ReturnType>(
+        path: string,
+        body: FormData | ConvertibleObject,
+        extra?: RequestInit,
+    ): Promise<Output<ReturnType>> {
+        return await this.request(
+            await this.constructRequest(
+                path,
+                "PATCH",
+                body instanceof FormData ? body : objectToFormData(body),
+                extra,
+            ),
+        );
+    }
+
+    protected async delete<ReturnType>(
+        path: string,
+        body?: object,
+        extra?: RequestInit,
+    ): Promise<Output<ReturnType>> {
+        return await this.request(
+            await this.constructRequest(path, "DELETE", body, extra),
+        );
+    }
+
+    protected async deleteForm<ReturnType>(
+        path: string,
+        body: FormData | ConvertibleObject,
+        extra?: RequestInit,
+    ): Promise<Output<ReturnType>> {
+        return await this.request(
+            await this.constructRequest(
+                path,
+                "DELETE",
+                body instanceof FormData ? body : objectToFormData(body),
+                extra,
+            ),
+        );
+    }
+}

client/lysand/constants.ts

@@ -0,0 +1,5 @@
+import pkg from "../package.json";
+
+export const NO_REDIRECT = "urn:ietf:wg:oauth:2.0:oob";
+export const DEFAULT_SCOPE = ["read", "write", "follow"];
+export const DEFAULT_UA = `LysandClient/${pkg.version} (+${pkg.homepage})`;

client/package.json

@@ -0,0 +1,60 @@
+{
+    "name": "@lysand-org/client",
+    "displayName": "Lysand Client",
+    "version": "0.0.0",
+    "author": {
+        "email": "jesse.wierzbinski@lysand.org",
+        "name": "Jesse Wierzbinski (CPlusPatch)",
+        "url": "https://cpluspatch.com"
+    },
+    "readme": "README.md",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/lysand-org/api.git",
+        "directory": "client"
+    },
+    "bugs": {
+        "url": "https://github.com/lysand-org/api/issues"
+    },
+    "license": "MIT",
+    "contributors": [
+        {
+            "name": "Jesse Wierzbinski",
+            "email": "jesse.wierzbinski@lysand.org",
+            "url": "https://cpluspatch.com"
+        }
+    ],
+    "maintainers": [
+        {
+            "name": "Jesse Wierzbinski",
+            "email": "jesse.wierzbinski@lysand.org",
+            "url": "https://cpluspatch.com"
+        }
+    ],
+    "description": "Client for Mastodon and Lysand API",
+    "categories": ["Other"],
+    "type": "module",
+    "engines": {
+        "bun": ">=1.1.8"
+    },
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "default": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/lysand"
+    },
+    "homepage": "https://lysand.org",
+    "keywords": ["lysand", "mastodon", "api", "typescript", "rest"],
+    "packageManager": "bun@1.1.8",
+    "dependencies": {
+        "@badgateway/oauth2-client": "^2.3.0",
+        "@types/mime-types": "^2.1.4",
+        "magic-regexp": "^0.8.0",
+        "mime-types": "^2.1.35"
+    }
+}

client/types/account.ts

@@ -0,0 +1,34 @@
+import type { Emoji } from "./emoji";
+import type { Field } from "./field";
+import type { Role } from "./role";
+import type { Source } from "./source";
+
+export type Account = {
+    id: string;
+    username: string;
+    acct: string;
+    display_name: string;
+    locked: boolean;
+    discoverable?: boolean;
+    group: boolean | null;
+    noindex: boolean | null;
+    suspended: boolean | null;
+    limited: boolean | null;
+    created_at: string;
+    followers_count: number;
+    following_count: number;
+    statuses_count: number;
+    note: string;
+    url: string;
+    avatar: string;
+    avatar_static: string;
+    header: string;
+    header_static: string;
+    emojis: Array<Emoji>;
+    moved: Account | null;
+    fields: Array<Field>;
+    bot: boolean | null;
+    source?: Source;
+    role?: Role;
+    mute_expires_at?: string;
+};

client/types/activity.ts

@@ -0,0 +1,6 @@
+export type Activity = {
+    week: string;
+    statuses: string;
+    logins: string;
+    registrations: string;
+};

client/types/announcement.ts

@@ -0,0 +1,39 @@
+import type { Emoji } from "./emoji";
+import type { StatusTag } from "./status";
+
+export type Announcement = {
+    id: string;
+    content: string;
+    starts_at: string | null;
+    ends_at: string | null;
+    published: boolean;
+    all_day: boolean;
+    published_at: string;
+    updated_at: string | null;
+    read: boolean | null;
+    mentions: Array<AnnouncementAccount>;
+    statuses: Array<AnnouncementStatus>;
+    tags: Array<StatusTag>;
+    emojis: Array<Emoji>;
+    reactions: Array<AnnouncementReaction>;
+};
+
+export type AnnouncementAccount = {
+    id: string;
+    username: string;
+    url: string;
+    acct: string;
+};
+
+export type AnnouncementStatus = {
+    id: string;
+    url: string;
+};
+
+export type AnnouncementReaction = {
+    name: string;
+    count: number;
+    me: boolean | null;
+    url: string | null;
+    static_url: string | null;
+};

client/types/application.ts

@@ -0,0 +1,14 @@
+export type Application = {
+    name: string;
+    website?: string | null;
+    vapid_key?: string | null;
+};
+
+export type ApplicationData = {
+    id: string;
+    name: string;
+    website?: string | null;
+    client_id: string;
+    client_secret: string;
+    vapid_key?: string | null;
+};

client/types/async_attachment.ts

@@ -0,0 +1,13 @@
+import type { Meta } from "./attachment";
+
+export type AsyncAttachment = {
+    id: string;
+    type: "unknown" | "image" | "gifv" | "video" | "audio";
+    url: string | null;
+    remote_url: string | null;
+    preview_url: string;
+    text_url: string | null;
+    meta: Meta | null;
+    description: string | null;
+    blurhash: string | null;
+};

client/types/attachment.ts

@@ -0,0 +1,47 @@
+export type Sub = {
+    // For Image, Gifv, and Video
+    width?: number;
+    height?: number;
+    size?: string;
+    aspect?: number;
+
+    // For Gifv and Video
+    frame_rate?: string;
+
+    // For Audio, Gifv, and Video
+    duration?: number;
+    bitrate?: number;
+};
+
+export type Focus = {
+    x: number;
+    y: number;
+};
+
+export type Meta = {
+    original?: Sub;
+    small?: Sub;
+    focus?: Focus;
+    length?: string;
+    duration?: number;
+    fps?: number;
+    size?: string;
+    width?: number;
+    height?: number;
+    aspect?: number;
+    audio_encode?: string;
+    audio_bitrate?: string;
+    audio_channel?: string;
+};
+
+export type Attachment = {
+    id: string;
+    type: "unknown" | "image" | "gifv" | "video" | "audio";
+    url: string;
+    remote_url: string | null;
+    preview_url: string | null;
+    text_url: string | null;
+    meta: Meta | null;
+    description: string | null;
+    blurhash: string | null;
+};

client/types/card.ts

@@ -0,0 +1,16 @@
+export type Card = {
+    url: string;
+    title: string;
+    description: string;
+    type: "link" | "photo" | "video" | "rich";
+    image: string | null;
+    author_name: string | null;
+    author_url: string | null;
+    provider_name: string | null;
+    provider_url: string | null;
+    html: string | null;
+    width: number | null;
+    height: number | null;
+    embed_url: string | null;
+    blurhash: string | null;
+};

client/types/context.ts

@@ -0,0 +1,6 @@
+import type { Status } from "./status";
+
+export type Context = {
+    ancestors: Array<Status>;
+    descendants: Array<Status>;
+};

client/types/conversation.ts

@@ -0,0 +1,9 @@
+import type { Account } from "./account";
+import type { Status } from "./status";
+
+export type Conversation = {
+    id: string;
+    accounts: Array<Account>;
+    last_status: Status | null;
+    unread: boolean;
+};

client/types/emoji.ts

@@ -0,0 +1,7 @@
+export type Emoji = {
+    shortcode: string;
+    static_url: string;
+    url: string;
+    visible_in_picker: boolean;
+    category?: string;
+};

client/types/featured_tag.ts

@@ -0,0 +1,6 @@
+export type FeaturedTag = {
+    id: string;
+    name: string;
+    statuses_count: number;
+    last_status_at: string;
+};

client/types/field.ts

@@ -0,0 +1,6 @@
+export type Field = {
+    name: string;
+    value: string;
+    verified_at?: string | null;
+    verified?: boolean | false;
+};

client/types/filter.ts

@@ -0,0 +1,10 @@
+export type Filter = {
+    id: string;
+    phrase: string;
+    context: Array<FilterContext>;
+    expires_at: string | null;
+    irreversible: boolean;
+    whole_word: boolean;
+};
+
+export type FilterContext = string;

client/types/follow_request.ts

@@ -0,0 +1,25 @@
+import type { Emoji } from "./emoji";
+import type { Field } from "./field";
+
+export type FollowRequest = {
+    id: number;
+    username: string;
+    acct: string;
+    display_name: string;
+    locked: boolean;
+    bot: boolean;
+    discoverable?: boolean;
+    group: boolean;
+    created_at: string;
+    note: string;
+    url: string;
+    avatar: string;
+    avatar_static: string;
+    header: string;
+    header_static: string;
+    followers_count: number;
+    following_count: number;
+    statuses_count: number;
+    emojis: Array<Emoji>;
+    fields: Array<Field>;
+};

client/types/history.ts

@@ -0,0 +1,5 @@
+export type History = {
+    day: string;
+    uses: number;
+    accounts: number;
+};

client/types/identity_proof.ts

@@ -0,0 +1,7 @@
+export type IdentityProof = {
+    provider: string;
+    provider_username: string;
+    updated_at: string;
+    proof_url: string;
+    profile_url: string;
+};

client/types/instance.ts

@@ -0,0 +1,38 @@
+import type { Account } from "./account";
+import type { Stats } from "./stats";
+import type { URLs } from "./urls";
+
+export type Instance = {
+    uri: string;
+    title: string;
+    description: string;
+    email: string;
+    version: string;
+    thumbnail: string | null;
+    urls: URLs | null;
+    stats: Stats;
+    languages: Array<string>;
+    registrations: boolean;
+    approval_required: boolean;
+    invites_enabled?: boolean;
+    configuration: {
+        statuses: {
+            max_characters: number;
+            max_media_attachments?: number;
+            characters_reserved_per_url?: number;
+        };
+        polls?: {
+            max_options: number;
+            max_characters_per_option: number;
+            min_expiration: number;
+            max_expiration: number;
+        };
+    };
+    contact_account?: Account;
+    rules?: Array<InstanceRule>;
+};
+
+export type InstanceRule = {
+    id: string;
+    text: string;
+};

client/types/list.ts

@@ -0,0 +1,7 @@
+export type List = {
+    id: string;
+    title: string;
+    replies_policy: RepliesPolicy | null;
+};
+
+export type RepliesPolicy = "followed" | "list" | "none";

client/types/marker.ts

@@ -0,0 +1,13 @@
+export type Marker = {
+    home?: {
+        last_read_id: string;
+        version: number;
+        updated_at: string;
+    };
+    notifications?: {
+        last_read_id: string;
+        version: number;
+        updated_at: string;
+        unread_count?: number;
+    };
+};

client/types/mention.ts

@@ -0,0 +1,6 @@
+export type Mention = {
+    id: string;
+    username: string;
+    url: string;
+    acct: string;
+};

client/types/notification.ts

@@ -0,0 +1,15 @@
+import type { Account } from "./account";
+import type { Reaction } from "./reaction";
+import type { Status } from "./status";
+
+export type Notification = {
+    account: Account | null;
+    created_at: string;
+    id: string;
+    status?: Status;
+    reaction?: Reaction;
+    type: NotificationType;
+    target?: Account;
+};
+
+export type NotificationType = string;

client/types/poll.ts

@@ -0,0 +1,14 @@
+export type Poll = {
+    id: string;
+    expires_at: string | null;
+    expired: boolean;
+    multiple: boolean;
+    votes_count: number;
+    options: Array<PollOption>;
+    voted: boolean;
+};
+
+export type PollOption = {
+    title: string;
+    votes_count: number | null;
+};

client/types/preferences.ts

@@ -0,0 +1,9 @@
+import type { StatusVisibility } from "./status";
+
+export type Preferences = {
+    "posting:default:visibility": StatusVisibility;
+    "posting:default:sensitive": boolean;
+    "posting:default:language": string | null;
+    "reading:expand:media": "default" | "show_all" | "hide_all";
+    "reading:expand:spoilers": boolean;
+};

client/types/push_subscription.ts

@@ -0,0 +1,14 @@
+export type Alerts = {
+    follow: boolean;
+    favourite: boolean;
+    mention: boolean;
+    reblog: boolean;
+    poll: boolean;
+};
+
+export type PushSubscription = {
+    id: string;
+    endpoint: string;
+    server_key: string;
+    alerts: Alerts;
+};

client/types/reaction.ts

@@ -0,0 +1,11 @@
+import type { Account } from "./account";
+
+export type Reaction = {
+    count: number;
+    me: boolean;
+    name: string;
+    url?: string;
+    static_url?: string;
+    accounts?: Array<Account>;
+    account_ids?: Array<string>;
+};

client/types/relationship.ts

@@ -0,0 +1,15 @@
+export type Relationship = {
+    id: string;
+    following: boolean;
+    followed_by: boolean;
+    blocking: boolean;
+    blocked_by: boolean;
+    muting: boolean;
+    muting_notifications: boolean;
+    requested: boolean;
+    domain_blocking: boolean;
+    showing_reblogs: boolean;
+    endorsed: boolean;
+    notifying: boolean;
+    note: string | null;
+};

client/types/report.ts

@@ -0,0 +1,16 @@
+import type { Account } from "./account";
+
+export type Report = {
+    id: string;
+    action_taken: boolean;
+    action_taken_at: string | null;
+    status_ids: Array<string> | null;
+    rule_ids: Array<string> | null;
+    // These parameters don't exist in Pleroma
+    category: Category | null;
+    comment: string | null;
+    forwarded: boolean | null;
+    target_account?: Account | null;
+};
+
+export type Category = "spam" | "violation" | "other";

client/types/results.ts

@@ -0,0 +1,9 @@
+import type { Account } from "./account";
+import type { Status } from "./status";
+import type { Tag } from "./tag";
+
+export type Results = {
+    accounts: Array<Account>;
+    statuses: Array<Status>;
+    hashtags: Array<Tag>;
+};

client/types/role.ts

@@ -0,0 +1,3 @@
+export type Role = {
+    name: string;
+};

client/types/scheduled_status.ts

@@ -0,0 +1,9 @@
+import type { Attachment } from "./attachment";
+import type { StatusParams } from "./status_params";
+
+export type ScheduledStatus = {
+    id: string;
+    scheduled_at: string;
+    params: StatusParams;
+    media_attachments: Array<Attachment> | null;
+};

client/types/source.ts

@@ -0,0 +1,9 @@
+import type { Field } from "./field";
+
+export type Source = {
+    privacy: string | null;
+    sensitive: boolean | null;
+    language: string | null;
+    note: string;
+    fields: Array<Field>;
+};

client/types/stats.ts

@@ -0,0 +1,5 @@
+export type Stats = {
+    user_count: number;
+    status_count: number;
+    domain_count: number;
+};

client/types/status.ts

@@ -0,0 +1,50 @@
+import type { Account } from "./account";
+import type { Application } from "./application";
+import type { Attachment } from "./attachment";
+import type { Card } from "./card";
+import type { Emoji } from "./emoji";
+import type { Mention } from "./mention";
+import type { Poll } from "./poll";
+import type { Reaction } from "./reaction";
+
+export type Status = {
+    id: string;
+    uri: string;
+    url: string;
+    account: Account;
+    in_reply_to_id: string | null;
+    in_reply_to_account_id: string | null;
+    reblog: Status | null;
+    content: string;
+    plain_content: string | null;
+    created_at: string;
+    edited_at: string | null;
+    emojis: Emoji[];
+    replies_count: number;
+    reblogs_count: number;
+    favourites_count: number;
+    reblogged: boolean | null;
+    favourited: boolean | null;
+    muted: boolean | null;
+    sensitive: boolean;
+    spoiler_text: string;
+    visibility: StatusVisibility;
+    media_attachments: Array<Attachment>;
+    mentions: Array<Mention>;
+    tags: Array<StatusTag>;
+    card: Card | null;
+    poll: Poll | null;
+    application: Application | null;
+    language: string | null;
+    pinned: boolean | null;
+    emoji_reactions: Array<Reaction>;
+    quote: boolean;
+    bookmarked: boolean;
+};
+
+export type StatusTag = {
+    name: string;
+    url: string;
+};
+
+export type StatusVisibility = "public" | "unlisted" | "private" | "direct";

client/types/status_params.ts

@@ -0,0 +1,12 @@
+import type { StatusVisibility } from "./status";
+
+export type StatusParams = {
+    text: string;
+    in_reply_to_id: string | null;
+    media_ids: Array<string> | null;
+    sensitive: boolean | null;
+    spoiler_text: string | null;
+    visibility: StatusVisibility | null;
+    scheduled_at: string | null;
+    application_id: number | null;
+};

client/types/status_source.ts

@@ -0,0 +1,5 @@
+export type StatusSource = {
+    id: string;
+    text: string;
+    spoiler_text: string;
+};

client/types/tag.ts

@@ -0,0 +1,8 @@
+import type { History } from "./history";
+
+export type Tag = {
+    name: string;
+    url: string;
+    history: Array<History>;
+    following?: boolean;
+};

client/types/token.ts

@@ -0,0 +1,6 @@
+export type Token = {
+    access_token: string;
+    token_type: string;
+    scope: string;
+    created_at: number;
+};

client/types/urls.ts

@@ -0,0 +1,3 @@
+export type URLs = {
+    streaming_api: string;
+};

tsconfig.json

@@ -20,7 +20,9 @@
         "allowJs": true,
         "emitDecoratorMetadata": false,
         "experimentalDecorators": true,
-        "verbatimModuleSyntax": true
+        "verbatimModuleSyntax": true,
+        "noUnusedLocals": true,
+        "noUnusedParameters": true
     },
     "include": ["*.ts", "*.d.ts", "**/*.ts", "**/*.d.ts"]
 }