bb-fca 2.0.1 → 2.0.3

package/src/deltas/apis/users/changeName.ts

@@ -0,0 +1,151 @@
+import { randomUUID } from 'crypto';
+
+/**
+ * @ChoruOfficial
+ * @description A module for changing the Facebook account display name via AccountsCenter.
+ * The name change process is two-step:
+ *  1. Preview: validate and preview the new name
+ *  2. Confirm: apply the name change mutation
+ * @param {Object} defaultFuncs The default functions provided by the API wrapper.
+ * @param {Object} api The full API object.
+ * @param {Object} ctx The context object containing the user's session state.
+ * @returns {Function} An async function that changes the account's display name.
+ */
+export default function(defaultFuncs: any, api: any, ctx: any) {
+  const ACCOUNTS_CENTER_URL = 'https://accountscenter.facebook.com/api/graphql/';
+
+  /**
+   * Builds the common form fields required by AccountsCenter GraphQL API.
+   * @private
+   */
+  function buildBaseForm() {
+    return {
+      av: ctx.userID,
+      __user: ctx.userID,
+      __a: '1',
+      fb_dtsg: ctx.fb_dtsg,
+      jazoest: ctx.jazoest,
+      lsd: ctx.lsd,
+      fb_api_caller_class: 'RelayModern',
+      server_timestamps: 'true',
+    };
+  }
+
+  /**
+   * Step 1 — Preview the new name to validate it and get a confirmation token.
+   * Calls `FXIMIdentityNameEditorAuthenticPreviewDialogQuery`.
+   * @private
+   * @param {string} firstName
+   * @param {string} lastName
+   * @param {string} [middleName='']
+   */
+  async function previewName(firstName: string, lastName: string, middleName = '') {
+    const variables = {
+      first_name: firstName,
+      last_name: lastName,
+      middle_name: middleName,
+      platform: 'FACEBOOK',
+      scale: 1,
+    };
+    const form = {
+      ...buildBaseForm(),
+      fb_api_req_friendly_name: 'FXIMIdentityNameEditorAuthenticPreviewDialogQuery',
+      variables: JSON.stringify(variables),
+      doc_id: '26302360049350115',
+    };
+    const res = await defaultFuncs.post(
+      ACCOUNTS_CENTER_URL,
+      ctx.jar,
+      form,
+      {
+        headers: {
+          'x-fb-friendly-name': 'FXIMIdentityNameEditorAuthenticPreviewDialogQuery',
+          'x-fb-lsd': ctx.lsd,
+          'x-asbd-id': '359341',
+          origin: 'https://accountscenter.facebook.com',
+          referer: `https://accountscenter.facebook.com/profiles/${ctx.userID}/name`,
+        },
+      },
+    );
+    if (res.data.errors) throw new Error(JSON.stringify(res.data.errors));
+    return res.data;
+  }
+
+  /**
+   * Step 2 — Confirm / apply the name change mutation.
+   * Calls `useFXIMUpdateNameMutation`.
+   * @private
+   * @param {string} firstName
+   * @param {string} lastName
+   * @param {string} [middleName='']
+   */
+  async function confirmName(firstName: string, lastName: string, middleName = '') {
+    const fullName = [firstName, middleName, lastName]
+      .filter(Boolean)
+      .join(' ');
+
+    const variables = {
+      client_mutation_id: randomUUID(),
+      family_device_id: 'device_id_fetch_datr',
+      identity_ids: [ctx.userID],
+      full_name: fullName,
+      first_name: firstName,
+      middle_name: middleName,
+      last_name: lastName,
+      interface: 'FB_WEB',
+    };
+    const form = {
+      ...buildBaseForm(),
+      fb_api_req_friendly_name: 'useFXIMUpdateNameMutation',
+      variables: JSON.stringify(variables),
+      doc_id: '9538143859625836',
+    };
+    const res = await defaultFuncs.post(
+      ACCOUNTS_CENTER_URL,
+      ctx.jar,
+      form,
+      {
+        headers: {
+          'x-fb-friendly-name': 'useFXIMUpdateNameMutation',
+          'x-fb-lsd': ctx.lsd,
+          'x-asbd-id': '359341',
+          origin: 'https://accountscenter.facebook.com',
+          referer: `https://accountscenter.facebook.com/profiles/${ctx.userID}/name`,
+        },
+      },
+    );
+    if (res.data.errors) throw new Error(JSON.stringify(res.data.errors));
+    return res.data;
+  }
+
+  /**
+   * Changes the account display name by first previewing, then confirming the mutation.
+   * @async
+   * @param {string} firstName - New first name (or full first portion).
+   * @param {string} lastName - New last name.
+   * @param {string} [middleName=''] - Optional middle name.
+   * @returns {Promise<{ preview: any; result: any }>} Resolves with preview and mutation result data.
+   * @throws {Error} If either the preview or confirm step fails.
+   *
+   * @example
+   * await api.changeName('Van Quy', 'Do');
+   * await api.changeName('Van Quy', 'Do', '');
+   */
+  return async function changeName(
+    firstName: string,
+    lastName: string,
+    middleName = '',
+  ): Promise<{ preview: any; result: any }> {
+    if (!firstName || !lastName) {
+      throw new Error('firstName and lastName are required.');
+    }
+
+    // Step 1: Preview / validate the name
+    const preview = await previewName(firstName, lastName, middleName);
+
+    // Step 2: Apply the name change
+    const result = await confirmName(firstName, lastName, middleName);
+
+    return { preview, result };
+  };
+}

package/src/deltas/apis/users/uploadAvatar.ts

@@ -0,0 +1,172 @@
+import * as fs from 'fs';
+import utils = require('../../../utils');
+
+/**
+ * @description A module for uploading a new profile picture (avatar) to Facebook.
+ * Two-step process:
+ *  1. Upload: sends the image file via multipart/form-data to /profile/picture/upload/
+ *  2. Set: calls ProfileCometProfilePictureSetMutation to apply the photo as avatar with optional caption
+ * @param {Object} defaultFuncs The default functions provided by the API wrapper.
+ * @param {Object} api The full API object.
+ * @param {Object} ctx The context object containing the user's session state.
+ * @returns {Function} An async function that uploads an avatar image.
+ */
+export default function (defaultFuncs: any, api: any, ctx: any) {
+  /**
+   * Step 2 — Apply the uploaded photo as avatar via ProfileCometProfilePictureSetMutation.
+   * @private
+   * @param {string} photoID The ID of the uploaded photo.
+   * @param {string} profileID The profile ID.
+   * @param {string} caption Optional caption for the avatar.
+   */
+  async function setProfilePicture(photoID: string, profileID: string, caption = '') {
+    const variables = {
+      input: {
+        attribution_id_v2: `ProfileCometTimelineListViewRoot.react,comet.profile.timeline.list,via_cold_start,${Date.now()},473818,190055527696468,,`,
+        caption: caption,
+        existing_photo_id: photoID,
+        expiration_time: null,
+        profile_id: profileID,
+        profile_pic_method: 'EXISTING',
+        profile_pic_source: 'TIMELINE',
+        scaled_crop_rect: { height: 0.56328, width: 1, x: 0, y: 0.21836 },
+        skip_cropping: true,
+        actor_id: ctx.userID,
+        client_mutation_id: Math.floor(Math.random() * 10 + 1).toString(),
+      },
+      isPage: false,
+      isProfile: true,
+      sectionToken: 'UNKNOWN',
+      collectionToken: 'UNKNOWN',
+      scale: 1,
+      '__relay_internal__pv__ProfileGeminiIsCoinFlipEnabledrelayprovider': false,
+    };
+
+    const form = {
+      av: ctx.userID,
+      __user: ctx.userID,
+      __a: '1',
+      fb_dtsg: ctx.fb_dtsg,
+      jazoest: ctx.jazoest,
+      lsd: ctx.lsd,
+      fb_api_caller_class: 'RelayModern',
+      fb_api_req_friendly_name: 'ProfileCometProfilePictureSetMutation',
+      variables: JSON.stringify(variables),
+      server_timestamps: 'true',
+      doc_id: '26101621736123633',
+    };
+
+    const res = await defaultFuncs.post(
+      'https://www.facebook.com/api/graphql/',
+      ctx.jar,
+      form,
+      {},
+    );
+    if (res.data.errors) throw new Error(JSON.stringify(res.data.errors));
+    return res.data;
+  }
+
+  /**
+   * Uploads a new profile picture (avatar) for the logged-in user, then sets it as avatar with optional caption.
+   * @async
+   * @param {string} imagePath The local file path to the image to upload.
+   * @param {string} [caption=''] Optional caption for the profile picture post.
+   * @param {string} [profileID=ctx.userID] The profile ID to upload the avatar for. Defaults to the logged-in user.
+   * @param {Function} [callback] Optional callback function.
+   * @returns {Promise<Object>} A promise that resolves with { upload, set } data on success.
+   * @throws {Error} If the imagePath is missing, the file does not exist, or any step fails.
+   *
+   * @example
+   * await api.uploadAvatar('/path/to/photo.jpg');
+   * await api.uploadAvatar('/path/to/photo.jpg', 'My new avatar!');
+   * await api.uploadAvatar('/path/to/photo.jpg', 'Caption', '61588408996667');
+   */
+  return async function uploadAvatar(
+    imagePath: string,
+    caption: string = '',
+    profileID: string = ctx.userID,
+    callback?,
+  ): Promise<any> {
+    let resolveFunc: Function = function () { };
+    let rejectFunc: Function = function () { };
+
+    const returnPromise = new Promise<any>(function (resolve, reject) {
+      resolveFunc = resolve;
+      rejectFunc = reject;
+    });
+
+    callback =
+      callback ||
+      function (err, data) {
+        if (err) return rejectFunc(err);
+        resolveFunc(data);
+      };
+
+    try {
+      if (!imagePath) throw new Error('imagePath is required.');
+      if (typeof imagePath !== 'string')
+        throw new Error('imagePath must be a string.');
+      if (!fs.existsSync(imagePath))
+        throw new Error(`File not found: ${imagePath}`);
+
+      // Step 1: Upload the photo
+      const photoStream = fs.createReadStream(imagePath);
+
+      const url = new URL('https://www.facebook.com/profile/picture/upload/');
+      url.searchParams.append('photo_source', '57');
+      url.searchParams.append('profile_id', profileID);
+      url.searchParams.append('av', ctx.userID);
+      url.searchParams.append('__aaid', '0');
+      url.searchParams.append('__user', ctx.userID);
+      url.searchParams.append('__a', '1');
+      url.searchParams.append('fb_dtsg', ctx.fb_dtsg);
+      url.searchParams.append('jazoest', ctx.jazoest);
+      url.searchParams.append('lsd', ctx.lsd);
+
+      const uploadResponse = await utils.postFormData(
+        url.toString(),
+        ctx.jar,
+        { file: photoStream },
+        ctx.globalOptions,
+        ctx,
+      );
+
+      const uploadResult = JSON.parse(
+        uploadResponse.body.toString().replace(/^for \(;;\);/, ''),
+      );
+
+      if (uploadResult.error || uploadResult.errors) {
+        throw new Error(
+          JSON.stringify(uploadResult.error || uploadResult.errors),
+        );
+      }
+
+      const photoID =
+        uploadResult.payload?.fbid ||
+        uploadResult.payload?.photoID ||
+        uploadResult.payload?.photo_id ||
+        null;
+
+      if (!photoID) {
+        throw new Error('Upload succeeded but could not extract photo ID from response.');
+      }
+
+      // Step 2: Set as profile picture with caption
+      const setResult = await setProfilePicture(photoID, profileID, caption);
+
+      const result = {
+        success: true,
+        photoID: photoID,
+        upload: uploadResult,
+        set: setResult,
+      };
+
+      callback(null, result);
+    } catch (err) {
+      utils.error('uploadAvatar', err);
+      callback(err);
+    }
+
+    return returnPromise;
+  };
+}

package/src/deltas/apis/users/uploadCover.ts

@@ -0,0 +1,167 @@
+import * as fs from 'fs';
+import utils = require('../../../utils');
+
+/**
+ * @ChoruOfficial
+ * @description A module for uploading a new cover photo (ảnh bìa) to Facebook.
+ * Two-step process:
+ *  1. Upload: sends the image file via multipart/form-data to /profile/cover/comet_upload/
+ *  2. Confirm: calls ProfileCometCoverPhotoUpdateMutation to apply the photo as cover
+ * @param {Object} defaultFuncs The default functions provided by the API wrapper.
+ * @param {Object} api The full API object.
+ * @param {Object} ctx The context object containing the user's session state.
+ * @returns {Function} An async function that uploads a cover photo.
+ */
+export default function (defaultFuncs: any, api: any, ctx: any) {
+  /**
+   * Step 2 — Confirm the uploaded photo as cover via ProfileCometCoverPhotoUpdateMutation.
+   * @private
+   * @param {string} photoID The ID of the uploaded photo.
+   * @param {string} profileID The profile ID.
+   * @param {{ x: number, y: number }} [focus] Optional focus point. Defaults to center {x:0.5, y:0.5}.
+   */
+  async function setCoverPhoto(
+    photoID: string,
+    profileID: string,
+    focus = { x: 0.5, y: 0.5 },
+  ) {
+    const variables = {
+      input: {
+        attribution_id_v2: `ProfileCometAboutTabRoot.react,comet.profile.collection.about,via_cold_start,${Date.now()},670164,,,`,
+        cover_photo_id: photoID,
+        focus: focus,
+        target_user_id: profileID,
+        actor_id: ctx.userID,
+        client_mutation_id: Math.floor(Math.random() * 10 + 1).toString(),
+      },
+      scale: 1,
+      contextualProfileContext: null,
+    };
+
+    const form = {
+      av: ctx.userID,
+      __user: ctx.userID,
+      __a: '1',
+      fb_dtsg: ctx.fb_dtsg,
+      jazoest: ctx.jazoest,
+      lsd: ctx.lsd,
+      fb_api_caller_class: 'RelayModern',
+      fb_api_req_friendly_name: 'ProfileCometCoverPhotoUpdateMutation',
+      variables: JSON.stringify(variables),
+      server_timestamps: 'true',
+      doc_id: '31388044007461211',
+    };
+
+    const res = await defaultFuncs.post(
+      'https://www.facebook.com/api/graphql/',
+      ctx.jar,
+      form,
+      {},
+    );
+    if (res.data.errors) throw new Error(JSON.stringify(res.data.errors));
+    return res.data;
+  }
+
+  /**
+   * Uploads a new cover photo (ảnh bìa) for the logged-in user, then confirms it as the cover.
+   * @async
+   * @param {string} imagePath The local file path to the image to upload.
+   * @param {string} [profileID=ctx.userID] The profile ID. Defaults to the logged-in user.
+   * @param {{ x: number, y: number }} [focus] Optional focus point for cropping. Defaults to {x:0.5, y:0.5}.
+   * @param {Function} [callback] Optional callback function.
+   * @returns {Promise<Object>} A promise that resolves with { upload, set } data on success.
+   * @throws {Error} If the imagePath is missing, the file does not exist, or any step fails.
+   *
+   * @example
+   * await api.uploadCover('/path/to/cover.jpg');
+   * await api.uploadCover('/path/to/cover.jpg', '61588408996667');
+   * await api.uploadCover('/path/to/cover.jpg', ctx.userID, { x: 0.5, y: 0.3 });
+   */
+  return async function uploadCover(
+    imagePath: string,
+    profileID: string = ctx.userID,
+    focus = { x: 0.5, y: 0.5 },
+    callback?,
+  ): Promise<any> {
+    let resolveFunc: Function = function () { };
+    let rejectFunc: Function = function () { };
+
+    const returnPromise = new Promise<any>(function (resolve, reject) {
+      resolveFunc = resolve;
+      rejectFunc = reject;
+    });
+
+    callback =
+      callback ||
+      function (err, data) {
+        if (err) return rejectFunc(err);
+        resolveFunc(data);
+      };
+
+    try {
+      if (!imagePath) throw new Error('imagePath is required.');
+      if (typeof imagePath !== 'string')
+        throw new Error('imagePath must be a string.');
+      if (!fs.existsSync(imagePath))
+        throw new Error(`File not found: ${imagePath}`);
+
+      // Step 1: Upload the photo
+      const photoStream = fs.createReadStream(imagePath);
+
+      const url = new URL('https://www.facebook.com/profile/cover/comet_upload/');
+      url.searchParams.append('profile_id', profileID);
+      url.searchParams.append('av', ctx.userID);
+      url.searchParams.append('__aaid', '0');
+      url.searchParams.append('__user', ctx.userID);
+      url.searchParams.append('__a', '1');
+      url.searchParams.append('fb_dtsg', ctx.fb_dtsg);
+      url.searchParams.append('jazoest', ctx.jazoest);
+      url.searchParams.append('lsd', ctx.lsd);
+
+      const uploadResponse = await utils.postFormData(
+        url.toString(),
+        ctx.jar,
+        { file: photoStream },
+        ctx.globalOptions,
+        ctx,
+      );
+
+      const uploadResult = JSON.parse(
+        uploadResponse.body.toString().replace(/^for \(;;\);/, ''),
+      );
+
+      if (uploadResult.error || uploadResult.errors) {
+        throw new Error(
+          JSON.stringify(uploadResult.error || uploadResult.errors),
+        );
+      }
+
+      const photoID =
+        uploadResult.payload?.fbid ||
+        uploadResult.payload?.photoID ||
+        uploadResult.payload?.photo_id ||
+        null;
+
+      if (!photoID) {
+        throw new Error('Upload succeeded but could not extract photo ID from response.');
+      }
+
+      // Step 2: Confirm as cover photo
+      const setResult = await setCoverPhoto(photoID, profileID, focus);
+
+      const result = {
+        success: true,
+        photoID: photoID,
+        upload: uploadResult,
+        set: setResult,
+      };
+
+      callback(null, result);
+    } catch (err) {
+      utils.error('uploadCover', err);
+      callback(err);
+    }
+
+    return returnPromise;
+  };
+}

package/src/types/index.d.ts

@@ -123,6 +123,13 @@ export interface UploadPhotoResult {
   data: any;
 }
 
+export interface ChangeNameResult {
+  /** Raw preview response data from AccountsCenter name validation query. */
+  preview: any;
+  /** Raw mutation result data confirming the name change. */
+  result: any;
+}
+
 export interface CurrentFriendInfo {
   userID: string;
   name: string;
@@ -637,6 +644,8 @@ export interface API {
     getCurrentFriends(
       callback?: Callback<CurrentFriendInfo[]>,
     ): Promise<CurrentFriendInfo[]>;
+    /** Send a friend request to a user by their ID via their profile page. */
+    add(userID: UserID, callback?: Callback): Promise<any>;
     suggest: {
       list(
         limit?: number,
@@ -690,6 +699,19 @@ export interface API {
 
   // ── Session ────────────────────────────────────────────────────
 
+  /**
+   * Changes the Facebook account display name (two-step: preview then confirm).
+   * Calls AccountsCenter GraphQL API.
+   * @param firstName New first name.
+   * @param lastName New last name.
+   * @param middleName Optional middle name (default: empty string).
+   */
+  changeName(
+    firstName: string,
+    lastName: string,
+    middleName?: string,
+  ): Promise<ChangeNameResult>;
+
   /** Log out and invalidate the current session. */
   logout(callback?: (err: any) => void): Promise<void>;