feat: Add explicit API versions to methods

BREAKING CHANGE: All API calls now require masto.v1 or masto.v2 as a prefix.

examples/create-new-status-with-image.ts

@@ -9,13 +9,13 @@ const main = async () => {
   });
 
   // Upload the image
-  const attachment = await masto.mediaAttachments.create({
+  const attachment = await masto.v2.mediaAttachments.create({
     file: fs.createReadStream('../some_image.png'),
     description: 'Some image',
   });
 
   // Publish!
-  const status = await masto.statuses.create({
+  const status = await masto.v1.statuses.create({
     status: 'Toot from TypeScript',
     visibility: 'direct',
     mediaIds: [attachment.id],

examples/create-new-status.ts

@@ -6,7 +6,7 @@ const main = async () => {
     accessToken: 'YOUR TOKEN',
   });
 
-  await masto.statuses.create({
+  await masto.v1.statuses.create({
     status: 'Toot from TypeScript',
     visibility: 'direct',
   });

examples/get-followers.ts

@@ -9,9 +9,9 @@ const main = async () => {
   });
 
   // Fetch your own account
-  const me = await masto.accounts.verifyCredentials();
+  const me = await masto.v1.accounts.verifyCredentials();
 
-  const { value: followers, done } = await masto.accounts.fetchFollowers(
+  const { value: followers, done } = await masto.v1.accounts.fetchFollowers(
     me.id,
     { limit: 60, minId: '123123' },
   );

examples/moderate-reports.ts

@@ -7,10 +7,10 @@ const main = async () => {
   });
 
   // Fetching reports
-  const reports = await masto.admin.report.fetchAll();
+  const reports = await masto.v1.admin.report.fetchAll();
 
   // Disable an account of the 1st report
-  await masto.admin.account.createAction(reports[0].account.id, {
+  await masto.v1.admin.account.createAction(reports[0].account.id, {
     type: 'disable',
     reportId: reports[0].id,
     text: 'Your account has been disabled',

examples/object-oriented.ts

@@ -1,4 +1,4 @@
-import type { MastoClient, Notification, Status } from 'masto';
+import type { MastoClient, V1 } from 'masto';
 import { login } from 'masto';
 
 class MyBot {
@@ -17,35 +17,35 @@ class MyBot {
   }
 
   async subscribe() {
-    const timeline = await this.masto.stream.streamUser();
+    const timeline = await this.masto.v1.stream.streamUser();
 
     // Add handlers
     timeline.on('update', this.handleUpdate);
     timeline.on('notification', this.handleNotification);
   }
 
-  private handleUpdate = (status: Status) => {
+  private handleUpdate = (status: V1.Status) => {
     const { content, account } = status;
     console.log(`${account.username} said ${content}`);
   };
 
-  private handleNotification = async (notification: Notification) => {
+  private handleNotification = async (notification: V1.Notification) => {
     // When your status got favourited, log
     if (notification.type === 'favourite') {
       console.log(`${notification.account.username} favourited your status!`);
     }
 
     // When you got a mention, reply
     if (notification.type === 'mention' && notification.status) {
-      await this.masto.statuses.create({
+      await this.masto.v1.statuses.create({
         status: 'I received your mention!',
         inReplyToId: notification.status.id,
       });
     }
 
     // When you got followed, follow them back
     if (notification.type === 'follow') {
-      await this.masto.accounts.follow(notification.account.id);
+      await this.masto.v1.accounts.follow(notification.account.id);
     }
   };
 }

examples/register-new-app.ts

@@ -5,7 +5,7 @@ const main = async () => {
     url: 'https://example.com',
   });
 
-  const app = await masto.apps.create({
+  const app = await masto.v1.apps.create({
     clientName: 'My app',
     redirectUris: 'urn:ietf:wg:oauth:2.0:oob',
     scopes: 'read write',

examples/timeline-rxjs.ts

@@ -1,14 +1,14 @@
-import type { Notification, Status } from 'masto';
+import type { V1 } from 'masto';
 import { login } from 'masto';
 import { fromEvent } from 'rxjs';
 import { filter, map } from 'rxjs/operators';
 
 const main = async () => {
   const masto = await login({ url: 'https://example.com' });
-  const timeline = await masto.stream.streamPublicTimeline();
+  const timeline = await masto.v1.stream.streamPublicTimeline();
 
-  const update$ = fromEvent<Status>(timeline, 'update');
-  const notification$ = fromEvent<Notification>(timeline, 'notifications');
+  const update$ = fromEvent<V1.Status>(timeline, 'update');
+  const notification$ = fromEvent<V1.Notification>(timeline, 'notifications');
 
   update$.subscribe((status) => {
     console.log(status.account.username);

examples/timeline-with-iterable.ts

@@ -5,7 +5,7 @@ const main = async () => {
     url: 'https://example.com',
   });
 
-  const result = await masto.timelines.fetchPublic({
+  const result = await masto.v1.timelines.fetchPublic({
     limit: 30,
   });
 
@@ -15,9 +15,9 @@ const main = async () => {
   console.log(result.value);
 
   // You can also use `for-await-of` syntax to iterate over the timeline
-  for await (const statuses of masto.timelines.iteratePublic()) {
+  for await (const statuses of masto.v1.timelines.iteratePublic()) {
     for (const status of statuses) {
-      masto.statuses.favourite(status.id);
+      masto.v1.statuses.favourite(status.id);
     }
   }
 };

examples/timeline-with-streaming.ts

@@ -7,7 +7,7 @@ const main = async () => {
   });
 
   // Connect to the streaming api
-  const stream = await masto.stream.streamPublicTimeline();
+  const stream = await masto.v1.stream.streamPublicTimeline();
 
   // Subscribe to updates
   stream.on('update', (status) => {

examples/update-profile.ts

@@ -8,7 +8,7 @@ const main = async () => {
     accessToken: 'YOUR TOKEN',
   });
 
-  const newProfile = await masto.accounts.updateCredentials({
+  const newProfile = await masto.v1.accounts.updateCredentials({
     displayName: 'Fluffy elephant friend',
     note: 'Hi fediverse!',
     avatar: fs.createReadStream('../some_image.png'),

src/api/index.ts

@@ -0,0 +1,4 @@
+export * as V1 from './v1';
+export * as V2 from './v2';
+export * from './repository';
+export * from './iterable-repository';

src/api/v1/entities/filter.ts

@@ -0,0 +1,25 @@
+export type FilterContext =
+  | 'home'
+  | 'notifications'
+  | 'public'
+  | 'thread'
+  | 'account';
+
+/**
+ * Represents a user-defined filter for determining which statuses should not be shown to the user.
+ * @see https://docs.joinmastodon.org/entities/filter/
+ */
+export interface Filter {
+  /** The ID of the filter in the database. */
+  id: string;
+  /** The text to be filtered. */
+  phrase: string;
+  /** The contexts in which the filter should be applied. */
+  context: FilterContext[];
+  /** When the filter should no longer be applied */
+  expiresAt?: string | null;
+  /** Should matching entities in home and notifications be dropped by the server? */
+  irreversible: boolean;
+  /** Should the filter consider word boundaries? */
+  wholeWord: boolean;
+}

src/entities/index.ts → src/api/v1/entities/index.ts

@@ -4,7 +4,7 @@ export * from './activity';
 export * as Admin from './admin';
 export * from './announcement';
 export * from './application';
-export * from './attachment';
+export * from './media-attachment';
 export * from './card';
 export * from './context';
 export * from './conversation';
@@ -26,7 +26,7 @@ export * from './preference';
 export * from './push-subscription';
 export * from './reaction';
 export * from './relationship';
-export * from './results';
+export * from './search';
 export * from './scheduled-status';
 export * from './source';
 export * from './status';
@@ -35,3 +35,4 @@ export * from './status-source';
 export * from './tag';
 export * from './token';
 export * from './suggestion';
+export * from './rule';

src/entities/instance.ts → src/api/v1/entities/instance.ts

@@ -1,4 +1,5 @@
-import type { Account } from '.';
+import type { Account } from './account';
+import type { Rule } from './rule';
 
 export interface InstanceStatusesConfiguration {
   maxCharacters: number;
@@ -73,7 +74,7 @@ export interface Instance {
   /** A user that can be contacted, as an alternative to `email`. */
   contactAccount?: Account | null;
 
-  rules?: InstanceRule[] | null;
+  rules?: Rule[] | null;
 }
 
 export interface InstanceURLs {
@@ -89,8 +90,3 @@ export interface InstanceStats {
   /** Domains federated with this instance. Number. */
   domainCount: number;
 }
-
-export interface InstanceRule {
-  id: string;
-  text: string;
-}

src/api/v1/entities/media-attachment.ts

@@ -0,0 +1,73 @@
+export type MediaAttachmentType =
+  | 'image'
+  | 'video'
+  | 'gifv'
+  | 'audio'
+  | 'unknown';
+
+export interface MediaAttachmentMetaImage {
+  width: number;
+  height: number;
+  size: string;
+  aspect: number;
+}
+
+export interface MediaAttachmentMetaVideo {
+  width: number;
+  height: number;
+  frameRate: string;
+  duration: number;
+  bitrate: number;
+  aspect: number;
+}
+
+export interface MediaAttachmentMetaFocus {
+  x: number;
+  y: number;
+}
+
+export interface MediaAttachmentMetaColors {
+  background: string;
+  foreground: string;
+  accent: string;
+}
+
+export interface MediaAttachmentMeta {
+  small?: MediaAttachmentMetaImage | MediaAttachmentMetaVideo | null;
+  original?: MediaAttachmentMetaImage | MediaAttachmentMetaVideo | null;
+  focus?: MediaAttachmentMetaFocus | null;
+  colors?: MediaAttachmentMetaColors | null;
+}
+
+/**
+ * Represents a file or media MediaAttachment that can be added to a status.
+ * @see https://docs.joinmastodon.org/entities/MediaAttachment/
+ */
+export interface MediaAttachment {
+  /** The ID of the MediaAttachment in the database. */
+  id: string;
+  /** The type of the MediaAttachment. */
+  type: MediaAttachmentType;
+  /** The location of the original full-size MediaAttachment. */
+  url?: string | null;
+  /** The location of a scaled-down preview of the MediaAttachment. */
+  previewUrl: string;
+  /** The location of the full-size original MediaAttachment on the remote website. */
+  remoteUrl?: string | null;
+  /** Remote version of previewUrl */
+  previewRemoteUrl?: string | null;
+  /** A shorter URL for the MediaAttachment. */
+  textUrl?: string | null;
+  /** Metadata returned by Paperclip. */
+  meta?: MediaAttachmentMeta | null;
+  /**
+   * Alternate text that describes what is in the media MediaAttachment,
+   * to be used for the visually impaired or when media MediaAttachments do not load.
+   */
+  description?: string | null;
+  /**
+   * A hash computed by the BlurHash algorithm,
+   * for generating colorful preview thumbnails when media has not been downloaded yet.
+   */
+  blurhash?: string | null;
+}

src/entities/push-subscription.ts → src/api/v1/entities/push-subscription.ts

@@ -1,19 +1,19 @@
 /**
  * Represents a subscription to the push streaming server.
- * @see https://docs.joinmastodon.org/entities/push-subscription/
+ * @see https://docs.joinmastodon.org/entities/WebPushSubscription/
  */
-export interface PushSubscription {
+export interface WebPushSubscription {
   /** The id of the push subscription in the database. */
   id: string;
   /** Where push alerts will be sent to. */
   endpoint: string;
   /** The streaming server's VAPID key. */
   serverKey: string;
   /** Which alerts should be delivered to the `endpoint`. */
-  alerts: PushSubscriptionAlerts;
+  alerts: WebPushSubscriptionAlerts;
 }
 
-export interface PushSubscriptionAlerts {
+export interface WebPushSubscriptionAlerts {
   /** Receive a push notification when someone has followed you? Boolean. */
   follow: boolean;
   /** Receive a push notification when a status you created has been favourited by someone else? Boolean. */
@@ -24,4 +24,14 @@ export interface PushSubscriptionAlerts {
   mention: boolean;
   /** Receive a push notification when a poll you voted in or created has ended? Boolean. */
   poll: boolean;
+  /** Receive new subscribed account notifications? Defaults to false. */
+  status: boolean;
+  /** Receive status edited notifications? Defaults to false. */
+  update: boolean;
+  admin: {
+    /** Receive new user signup notifications? Defaults to false. Must have a role with the appropriate permissions. */
+    signUp: boolean;
+    /** Receive new report notifications? Defaults to false. Must have a role with the appropriate permissions. */
+    report: boolean;
+  };
 }

src/api/v1/entities/rule.ts

@@ -0,0 +1,4 @@
+export interface Rule {
+  id: string;
+  text: string;
+}