@juzi/wechaty
Version:
Wechaty is a RPA SDK for Chatbot Makers.
447 lines (446 loc) • 19 kB
TypeScript
/**
* Wechaty Chatbot SDK - https://github.com/wechaty/wechaty
*
* @copyright 2016 Huan LI (李卓桓) <https://github.com/huan>, and
* Wechaty Contributors <https://github.com/wechaty>.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
import * as PUPPET from '@juzi/wechaty-puppet';
import { type FileBoxInterface } from 'file-box';
import type { Constructor } from 'clone-class';
import { SayOptions } from '../sayable/mod.js';
import type { SayableSayer, Sayable } from '../sayable/mod.js';
import { ContactInterface, ContactImpl } from './contact.js';
import type { MessageInterface } from './message.js';
declare const MixinBase: ((abstract new (...args: any[]) => {
readonly wechaty: import("../wechaty/wechaty-impl.js").WechatyInterface;
}) & {
readonly wechaty: import("../wechaty/wechaty-impl.js").WechatyInterface;
}) & ((abstract new (...args: any[]) => {}) & {
_pool?: Map<string, RoomImplInterface> | undefined;
readonly pool: Map<string, RoomImplInterface>;
load<L extends import("clone-class/dist/esm/src/constructor.js").ClassInterface<{}> & {
new (...args: any[]): RoomImplInterface;
prototype: RoomImplInterface;
} & import("../user-mixins/poolify.js").PoolifyMixin<RoomImplInterface>>(this: L, id: string): RoomImplInterface;
}) & (new () => import("typed-emitter").default<import("../schemas/room-events.js").RoomEventListeners>);
/**
* All WeChat rooms(groups) will be encapsulated as a Room.
*
* [Examples/Room-Bot]{@link https://github.com/wechaty/wechaty/blob/1523c5e02be46ebe2cc172a744b2fbe53351540e/examples/room-bot.ts}
*
*/
declare class RoomMixin extends MixinBase implements SayableSayer {
readonly id: string;
/**
* Create a new room.
*
* @static
* @param {ContactInterface[]} contactList
* @param {string} [topic]
* @returns {Promise<RoomInterface>}
* @example <caption>Creat a room with 'lijiarui' and 'huan', the room topic is 'ding - created'</caption>
* const helperContactA = await Contact.find({ name: 'lijiarui' }) // change 'lijiarui' to any contact in your WeChat
* const helperContactB = await Contact.find({ name: 'huan' }) // change 'huan' to any contact in your WeChat
* const contactList = [helperContactA, helperContactB]
* console.log('Bot', 'contactList: %s', contactList.join(','))
* const room = await Room.create(contactList, 'ding')
* console.log('Bot', 'createDingRoom() new ding room created: %s', room)
* await room.topic('ding - created')
* await room.say('ding - created')
*/
static create(contactList: ContactInterface[], topic?: string): Promise<RoomInterface>;
/**
* Parse the dynamic QR Code of the room
* @param {string} url
* @returns {Promise<PUPPET.types.RoomParseDynamicQRCode>}
*/
static parseDynamicQRCode(url: string): Promise<PUPPET.types.RoomParseDynamicQRCode>;
/**
* The filter to find the room: {topic: string | RegExp}
*
* @typedef RoomQueryFilter
* @property {string} topic
*/
/**
* Find room by filter: {topic: string | RegExp}, return all the matched room.
*
* NOTE: The returned list would be limited by the underlying puppet
* implementation of `puppet.roomList`. Some implementation (i.e.
* wechaty-puppet-wechat) would only return rooms which have received messges
* after a log-in.
*
* @static
* @param {RoomQueryFilter} [query]
* @returns {Promise<RoomInterface[]>}
* @example
* const bot = new Wechaty()
* await bot.start()
* // after logged in
* const roomList = await bot.Room.findAll() // get the room list of the bot
* const roomList = await bot.Room.findAll({topic: 'wechaty'}) // find all of the rooms with name 'wechaty'
*/
static findAll(query?: PUPPET.filters.Room): Promise<RoomInterface[]>;
/**
* Try to find a room by filter: {topic: string | RegExp}. If get many, return the first one.
*
* NOTE: The search space is limited by the underlying puppet
* implementation of `puppet.roomList`. Some implementation (i.e.
* wechaty-puppet-wechat) would only return rooms which have received messges
* after a log-in.
*
* @param {RoomQueryFilter} query
* @returns {Promise<undefined | RoomInterface>} If can find the room, return Room, or return null
* @example
* const bot = new Wechaty()
* await bot.start()
* // after logged in...
* const roomList = await bot.Room.find()
* const roomList = await bot.Room.find({topic: 'wechaty'})
*/
static find(query: string | PUPPET.filters.Room): Promise<undefined | RoomInterface>;
static batchLoadRooms(roomIdList: string[]): Promise<RoomInterface[]>;
/** const roomList: RoomInterface[] = []
* @ignore
*
* Instance Properties
*
*
*/
payload?: PUPPET.payloads.Room;
/**
* @hideconstructor
* @property {string} id - Room id.
* This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table)
*/
constructor(id: string);
/**
* @ignore
*/
toString(): string;
[Symbol.asyncIterator](): AsyncIterableIterator<ContactInterface>;
/**
* Proposal: add a handle field to RoomPayload #181
* @link https://github.com/wechaty/puppet/issues/181
*/
handle(): undefined | string;
/**
* Force reload data for Room, Sync data from puppet API again.
*
* @returns {Promise<void>}
* @example
* await room.sync()
*/
sync(): Promise<void>;
/**
* Warning: `ready()` is for the framework internally use ONLY!
*
* Please not to use `ready()` at the user land.
* If you want to sync data, use `sync()` instead.
*
* @ignore
*/
ready(forceSync?: boolean): Promise<void>;
/**
* @ignore
*/
isReady(): boolean;
say(sayable: Sayable): Promise<void | MessageInterface>;
say(text: string, options?: SayOptions): Promise<void | MessageInterface>;
say(text: string, ...options: SayOptions[]): Promise<void | MessageInterface>;
say(textList: TemplateStringsArray, ...varList: any[]): Promise<void | MessageInterface>;
private sayTemplateStringsArray;
/**
* @desc Room Class Event Type
* @typedef RoomEventName
* @property {string} join - Emit when anyone join any room.
* @property {string} topic - Get topic event, emitted when someone change room topic.
* @property {string} leave - Emit when anyone leave the room.<br>
* If someone leaves the room by themselves, WeChat will not notice other people in the room, so the bot will never get the "leave" event.
*/
/**
* @desc Room Class Event Function
* @typedef RoomEventFunction
* @property {Function} room-join - (this: Room, inviteeList: Contact[] , inviter: Contact) => void
* @property {Function} room-topic - (this: Room, topic: string, oldTopic: string, changer: Contact) => void
* @property {Function} room-leave - (this: Room, leaver: Contact) => void
*/
/**
* @listens Room
* @param {RoomEventName} event - Emit WechatyEvent
* @param {RoomEventFunction} listener - Depends on the WechatyEvent
* @return {this} - this for chain
*
* @example <caption>Event:join </caption>
* const bot = new Wechaty()
* await bot.start()
* // after logged in...
* const room = await bot.Room.find({topic: 'topic of your room'}) // change `event-room` to any room topic in your WeChat
* if (room) {
* room.on('join', (room, inviteeList, inviter) => {
* const nameList = inviteeList.map(c => c.name()).join(',')
* console.log(`Room got new member ${nameList}, invited by ${inviter}`)
* })
* }
*
* @example <caption>Event:leave </caption>
* const bot = new Wechaty()
* await bot.start()
* // after logged in...
* const room = await bot.Room.find({topic: 'topic of your room'}) // change `event-room` to any room topic in your WeChat
* if (room) {
* room.on('leave', (room, leaverList) => {
* const nameList = leaverList.map(c => c.name()).join(',')
* console.log(`Room lost member ${nameList}`)
* })
* }
*
* @example <caption>Event:message </caption>
* const bot = new Wechaty()
* await bot.start()
* // after logged in...
* const room = await bot.Room.find({topic: 'topic of your room'}) // change `event-room` to any room topic in your WeChat
* if (room) {
* room.on('message', (message) => {
* console.log(`Room received new message: ${message}`)
* })
* }
*
* @example <caption>Event:topic </caption>
* const bot = new Wechaty()
* await bot.start()
* // after logged in...
* const room = await bot.Room.find({topic: 'topic of your room'}) // change `event-room` to any room topic in your WeChat
* if (room) {
* room.on('topic', (room, topic, oldTopic, changer) => {
* console.log(`Room topic changed from ${oldTopic} to ${topic} by ${changer.name()}`)
* })
* }
*
* @example <caption>Event:invite </caption>
* const bot = new Wechaty()
* await bot.start()
* // after logged in...
* const room = await bot.Room.find({topic: 'topic of your room'}) // change `event-room` to any room topic in your WeChat
* if (room) {
* room.on('invite', roomInvitation => roomInvitation.accept())
* }
*
*/
/**
* Add contact in a room
*
* > Tips:
* This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table)
* >
* > see {@link https://github.com/wechaty/wechaty/issues/1441|Web version of WeChat closed group interface}
*
* @param {ContactInterface} contact
* @returns {Promise<void>}
* @example
* const bot = new Wechaty()
* await bot.start()
* // after logged in...
* const contact = await bot.Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any contact in your WeChat
* const room = await bot.Room.find({topic: 'WeChat'}) // change 'WeChat' to any room topic in your WeChat
* if (room) {
* try {
* await room.add(contact)
* } catch(e) {
* console.error(e)
* }
* }
*/
add(contact: ContactInterface, quoteIds?: string[]): Promise<void>;
addV2(contacts: ContactInterface[], quoteIds?: string[]): Promise<{
successList: ContactInterface[];
failList: ContactInterface[];
failReasonList: string[];
}>;
/**
* Remove a contact from the room
* It works only when the bot is the owner of the room
*
* > Tips:
* This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table)
* >
* > see {@link https://github.com/wechaty/wechaty/issues/1441|Web version of WeChat closed group interface}
*
* @param {ContactInterface} contact
* @returns {Promise<void>}
* @example
* const bot = new Wechaty()
* await bot.start()
* // after logged in...
* const room = await bot.Room.find({topic: 'WeChat'}) // change 'WeChat' to any room topic in your WeChat
* const contact = await bot.Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any room member in the room you just set
* if (room) {
* try {
* await room.remove(contact)
* } catch(e) {
* console.error(e)
* }
* }
*/
remove(contacts: ContactInterface | ContactInterface[]): Promise<void>;
removeV2(contacts: ContactInterface[]): Promise<{
successList: ContactInterface[];
failList: ContactInterface[];
failReasonList: string[];
}>;
/**
* Huan(202106): will be removed after Dec 31, 2023
* @deprecated use remove(contact) instead.
*/
del(contact: ContactImpl | ContactImpl[]): Promise<void>;
dismiss(): Promise<void>;
/**
* Bot quit the room itself
*
* > Tips:
* This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table)
*
* @returns {Promise<void>}
* @example
* await room.quit()
*/
quit(): Promise<void>;
topic(): Promise<string>;
topic(newTopic: string): Promise<void>;
announce(): Promise<string>;
announce(text: string): Promise<void>;
/**
* Get QR Code Value of the Room from the room, which can be used as scan and join the room.
* > Tips:
* 1. This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table)
* 2. The return should be the QR Code Data, instead of the QR Code Image. (the data should be less than 8KB. See: https://stackoverflow.com/a/12764370/1123955 )
* @returns {Promise<string>}
*/
qrCode(): Promise<string>;
/**
* Return contact's roomAlias in the room
* @param {ContactInterface} contact
* @returns {Promise<string | null>} - If a contact has an alias in room, return string, otherwise return null
* @example
* const bot = new Wechaty()
* bot
* .on('message', async m => {
* const room = m.room()
* const contact = m.from()
* if (room) {
* const alias = await room.alias(contact)
* console.log(`${contact.name()} alias is ${alias}`)
* }
* })
* .start()
*/
alias(contact: ContactInterface): Promise<undefined | string>;
joinScene(contact: ContactInterface): Promise<PUPPET.types.RoomMemberJoinScene>;
joinTime(contact: ContactInterface): Promise<undefined | number>;
joinInviter(contact: ContactInterface): Promise<undefined | ContactInterface>;
readMark(hasRead: boolean): Promise<void>;
readMark(): Promise<boolean>;
endConversation(): Promise<void>;
/**
* Check if the room has member `contact`, the return is a Promise and must be `await`-ed
*
* @param {ContactInterface} contact
* @returns {Promise<boolean>} Return `true` if has contact, else return `false`.
* @example <caption>Check whether 'lijiarui' is in the room 'wechaty'</caption>
* const bot = new Wechaty()
* await bot.start()
* // after logged in...
* const contact = await bot.Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any of contact in your WeChat
* const room = await bot.Room.find({topic: 'wechaty'}) // change 'wechaty' to any of the room in your WeChat
* if (contact && room) {
* if (await room.has(contact)) {
* console.log(`${contact.name()} is in the room wechaty!`)
* } else {
* console.log(`${contact.name()} is not in the room wechaty!`)
* }
* }
*/
has(contact: ContactInterface): Promise<boolean>;
memberAll(): Promise<ContactInterface[]>;
memberAll(name: string): Promise<ContactInterface[]>;
memberAll(filter: PUPPET.filters.RoomMember): Promise<ContactInterface[]>;
member(name: string): Promise<undefined | ContactInterface>;
member(filter: PUPPET.filters.RoomMember): Promise<undefined | ContactInterface>;
/**
* Huan(202110):
* - Q: why this method marked as `privated` before?
* - A: it is for supporting the `memberAll()` API
*
* Get all room member from the room
*
* @returns {Promise<ContactInterface[]>}
* @example
* await room.memberList()
*/
protected memberList(): Promise<ContactInterface[]>;
/**
* Get room's owner from the room.
* > Tips:
* This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table)
* @returns {(ContactInterface | undefined)}
* @example
* const owner = room.owner()
*/
owner(): undefined | ContactInterface;
/**
* Get room's admin list from the room.
* > Tips:
* This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table)
* @returns {(ContactInterface[])}
* @example
* const adminList = room.adminList()
*/
adminList(): Promise<ContactInterface[]>;
/**
* Get avatar from the room.
* @returns {FileBox}
* @example
* const fileBox = await room.avatar()
* const name = fileBox.name
* fileBox.toFile(name)
*/
avatar(): Promise<FileBoxInterface>;
avatar(avatar: FileBoxInterface): Promise<void>;
additionalInfo(): undefined | any;
remark(remark?: string): Promise<undefined | string>;
permission(permission?: Partial<PUPPET.types.RoomPermission>): Promise<void | Partial<PUPPET.types.RoomPermission>>;
addAdmins(contactList: ContactInterface[]): Promise<void>;
delAdmins(contactList: ContactInterface[]): Promise<void>;
transfer(contact: ContactInterface): Promise<void>;
external(): boolean | undefined;
createDate(): Date | undefined;
memberPayloads(): Promise<Map<string, PUPPET.payloads.RoomMember>>;
}
declare const RoomImpl_base: {
new (...args: any[]): {};
valid: (o: any) => o is RoomImplInterface;
validInstance: (target: any) => target is RoomMixin;
validInterface: (target: any) => target is RoomImplInterface;
} & typeof RoomMixin;
declare class RoomImpl extends RoomImpl_base {
}
interface RoomImplInterface extends RoomImpl {
}
declare type RoomProtectedProperty = 'ready';
declare type RoomInterface = Omit<RoomImplInterface, RoomProtectedProperty>;
declare type RoomConstructor = Constructor<RoomImplInterface, Omit<typeof RoomImpl, 'load'>>;
export type { RoomConstructor, RoomProtectedProperty, RoomInterface, };
export { RoomImpl, };
//# sourceMappingURL=room.d.ts.map