feat(relation): add id/phone contact lookups and add-friend helpers

example/relation/addfriend.ts

@@ -20,3 +20,26 @@ await client.relation.addFriendByMid({
     trackingMetaHint: "uhex",
     trackingMetaType: 4,
 })
+
+
+// by LINE ID — searches then adds. Official Accounts include the leading "@"
+await client.relation.addFriendByUserId({
+    userId: "@livecast",
+})
+
+// or resolve the mid yourself
+const contact = await client.relation.findContactBySearchIdOrTicketV3({
+    searchId: "@livecast",
+})
+console.log(contact.mid, contact.displayName)
+
+
+// by phone number (E.164, e.g. +<country><number> without a leading 0)
+await client.relation.addFriendByPhone({
+    phone: "+66814298575",
+})
+
+const byPhone = await client.relation.findContactByPhoneV3({
+    phone: "+66814298575",
+})
+console.log(byPhone.mid, byPhone.displayName)

packages/linejs/base/service/relation/mod.ts

@@ -130,4 +130,71 @@ export class RelationService implements BaseService {
 			this.requestPath,
 		);
 	}
+
+	/**
+	 * @description Find a contact by its search id (the user's LINE ID). Official
+	 * Accounts include the leading `@`, e.g. `@livecast`. Throws when nothing matches
+	 * or the id search is rate limited.
+	 */
+	public async findContactBySearchIdOrTicketV3(options: {
+		searchId: string;
+	}): Promise<LINETypes.Contact> {
+		const { searchId } = options;
+		return await this.client.request.request(
+			[[12, 1, [[12, 1, [[11, 1, searchId]]]]]],
+			"findContactBySearchIdOrTicketV3",
+			this.protocolType,
+			"Contact",
+			this.requestPath,
+		);
+	}
+
+	/**
+	 * @description Search a user by their LINE ID and add them as a friend. Official
+	 * Account IDs include the leading `@`.
+	 */
+	public async addFriendByUserId(options: {
+		userId: string;
+	}): Promise<LooseType> {
+		const contact = await this.findContactBySearchIdOrTicketV3({
+			searchId: options.userId,
+		});
+		return await this.addFriendByMid({
+			mid: contact.mid,
+			reference: '{"screen":"friendAdd:idSearch","spec":"native"}',
+			trackingMetaType: 2,
+			trackingMetaHint: options.userId,
+		});
+	}
+
+	/**
+	 * @description Find a contact by phone number. The number is in E.164 form,
+	 * e.g. `+66814298575`. Throws when nothing matches or the lookup is rate limited.
+	 */
+	public async findContactByPhoneV3(options: {
+		phone: string;
+	}): Promise<LINETypes.Contact> {
+		return await this.client.request.request(
+			[[12, 1, [[11, 1, options.phone]]]],
+			"findContactByPhoneV3",
+			this.protocolType,
+			"Contact",
+			this.requestPath,
+		);
+	}
+
+	/**
+	 * @description Look up a user by phone number (E.164) and add them as a friend.
+	 */
+	public async addFriendByPhone(options: {
+		phone: string;
+	}): Promise<LooseType> {
+		const contact = await this.findContactByPhoneV3({ phone: options.phone });
+		return await this.addFriendByMid({
+			mid: contact.mid,
+			reference: '{"screen":"friendAdd:phoneSearch","spec":"native"}',
+			trackingMetaType: 2,
+			trackingMetaHint: options.phone,
+		});
+	}
 }