wechaty-puppet
Version:
Abstract Puppet for Wechaty
286 lines (285 loc) • 11.7 kB
TypeScript
/**
* Wechaty - https://github.com/chatie/wechaty
*
* @copyright 2016-2018 Huan LI <zixia@zixia.net>
*
* 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.
*
*/
/// <reference types="node" />
import { EventEmitter } from 'events';
import LRU from 'lru-cache';
import { FileBox } from 'file-box';
import { MemoryCard } from 'memory-card';
import { StateSwitch } from 'state-switch';
import { WatchdogFood } from 'watchdog';
import { ContactPayload, ContactPayloadFilterFunction, ContactQueryFilter } from './schemas/contact';
import { FriendshipPayload } from './schemas/friendship';
import { MessagePayload } from './schemas/message';
import { RoomMemberPayload, RoomMemberQueryFilter, RoomPayload, RoomPayloadFilterFunction, RoomQueryFilter } from './schemas/room';
import { RoomInvitationPayload } from './schemas/room-invitation';
import { PuppetOptions, Receiver, YOU } from './schemas/puppet';
/**
*
* Puppet Base Class
*
* See: https://github.com/Chatie/wechaty/wiki/Puppet
*
*/
export declare abstract class Puppet extends EventEmitter {
protected options: PuppetOptions;
/**
* Must overwrite by child class to identify their version
*/
static readonly VERSION: string;
protected readonly cacheContactPayload: LRU.Cache<string, ContactPayload>;
protected readonly cacheFriendshipPayload: LRU.Cache<string, FriendshipPayload>;
protected readonly cacheMessagePayload: LRU.Cache<string, MessagePayload>;
protected readonly cacheRoomPayload: LRU.Cache<string, RoomPayload>;
protected readonly cacheRoomMemberPayload: LRU.Cache<string, RoomMemberPayload>;
protected readonly state: StateSwitch;
protected readonly counter: number;
protected memory: MemoryCard;
/**
* Login-ed User ID
*/
protected id?: string;
private readonly watchdog;
/**
* childPkg stores the `package.json` that the NPM module who extends the `Puppet`
*/
private readonly childPkg;
/**
* Throttle Reset Events
*/
private resetThrottleQueue;
/**
*
*
* Constructor
*
*
*/
constructor(options?: PuppetOptions);
toString(): string;
/**
* Unref
*/
unref(): void;
/**
* @private
*
* For used by Wechaty internal ONLY.
*/
setMemory(memory: MemoryCard): void;
/**
*
*
* Events
*
*
*/
emit(event: 'dong', data?: string): boolean;
emit(event: 'error', error: Error): boolean;
emit(event: 'friendship', friendshipId: string): boolean;
emit(event: 'login', contactId: string): boolean;
emit(event: 'logout', contactId: string): boolean;
emit(event: 'message', messageId: string): boolean;
emit(event: 'reset', reason: string): boolean;
emit(event: 'room-join', roomId: string, inviteeIdList: string[], inviterId: string): boolean;
emit(event: 'room-leave', roomId: string, leaverIdList: string[], remover?: string): boolean;
emit(event: 'room-topic', roomId: string, newTopic: string, oldTopic: string, changerId: string): boolean;
emit(event: 'room-invite', roomInvitationId: string): boolean;
emit(event: 'scan', qrcode: string, status: number, data?: string): boolean;
emit(event: 'watchdog', food: WatchdogFood): boolean;
emit(event: never, ...args: never[]): never;
/**
*
*
* Listeners
*
*
*/
on(event: 'dong', listener: (data?: string) => void): this;
on(event: 'error', listener: (error: string) => void): this;
on(event: 'friendship', listener: (friendshipId: string) => void): this;
on(event: 'login', listener: (contactId: string) => void): this;
on(event: 'logout', listener: (contactId: string) => void): this;
on(event: 'message', listener: (messageId: string) => void): this;
on(event: 'reset', listener: (reason: string) => void): this;
on(event: 'room-join', listener: (roomId: string, inviteeIdList: string[], inviterId: string) => void): this;
on(event: 'room-leave', listener: (roomId: string, leaverIdList: string[], removerId?: string) => void): this;
on(event: 'room-topic', listener: (roomId: string, newTopic: string, oldTopic: string, changerId: string) => void): this;
on(event: 'room-invite', listener: (roomInvitationId: string) => void): this;
on(event: 'scan', listener: (qrcode: string, status: number, data?: string) => void): this;
on(event: 'watchdog', listener: (data: WatchdogFood) => void): this;
on(event: never, listener: never): never;
/**
*
*
* Start / Stop
*
*
*/
abstract start(): Promise<void>;
abstract stop(): Promise<void>;
/**
* reset() Should not be called directly.
* `protected` is for testing, not for the child class.
* should use `emit('reset', 'reason')` instead.
* Huan, July 2018
*/
protected reset(reason: string): void;
/**
*
*
* Login / Logout
*
*
*/
/**
* Need to be called internaly when the puppet is logined.
* this method will emit a `login` event
*/
protected login(userId: string): Promise<void>;
/**
* Need to be called internaly/externaly when the puppet need to be logouted
* this method will emit a `logout` event,
*
* Note: must set `this.id = undefined` in this function.
*/
abstract logout(): Promise<void>;
selfId(): string;
logonoff(): boolean;
/**
*
*
* Misc
*
*
*/
/**
* Check whether the puppet is work property.
* @returns `false` if something went wrong
* 'dong' if everything is OK
*/
abstract ding(data?: string): void;
/**
* Get version from the Puppet Implementation
*/
version(): string;
/**
* will be used by semver.satisfied(version, range)
*/
wechatyVersionRange(strict?: boolean): string;
/**
*
* Contact
*
*/
abstract contactAlias(contactId: string): Promise<string>;
abstract contactAlias(contactId: string, alias: string | null): Promise<void>;
abstract contactAvatar(contactId: string): Promise<FileBox>;
abstract contactAvatar(contactId: string, file: FileBox): Promise<void>;
abstract contactList(): Promise<string[]>;
abstract contactQrcode(contactId: string): Promise<string>;
protected abstract contactRawPayload(contactId: string): Promise<any>;
protected abstract contactRawPayloadParser(rawPayload: any): Promise<ContactPayload>;
contactRoomList(contactId: string): Promise<string[]>;
protected contactPayloadDirty(contactId: string): Promise<void>;
contactSearch(query?: string | ContactQueryFilter, searchIdList?: string[]): Promise<string[]>;
protected contactQueryFilterFactory(query: ContactQueryFilter): ContactPayloadFilterFunction;
/**
* Check a Contact Id if it's still valid.
* For example: talk to the server, and see if it should be deleted in the local cache.
*/
contactValidate(contactId: string): Promise<boolean>;
protected contactPayloadCache(contactId: string): undefined | ContactPayload;
contactPayload(contactId: string): Promise<ContactPayload>;
/**
*
* Friendship
*
*/
abstract friendshipAdd(contactId: string, hello?: string): Promise<void>;
abstract friendshipAccept(friendshipId: string): Promise<void>;
protected abstract friendshipRawPayload(friendshipId: string): Promise<any>;
protected abstract friendshipRawPayloadParser(rawPayload: any): Promise<FriendshipPayload>;
protected friendshipPayloadCache(friendshipId: string): undefined | FriendshipPayload;
protected friendshipPayloadDirty(friendshipId: string): Promise<void>;
friendshipPayload(friendshipId: string): Promise<FriendshipPayload>;
/**
*
* Message
*
*/
abstract messageFile(messageId: string): Promise<FileBox>;
abstract messageForward(receiver: Receiver, messageId: string): Promise<void>;
abstract messageSendText(receiver: Receiver, text: string): Promise<void>;
abstract messageSendContact(receiver: Receiver, contactId: string): Promise<void>;
abstract messageSendFile(receiver: Receiver, file: FileBox): Promise<void>;
protected abstract messageRawPayload(messageId: string): Promise<any>;
protected abstract messageRawPayloadParser(rawPayload: any): Promise<MessagePayload>;
protected messagePayloadCache(messageId: string): undefined | MessagePayload;
protected messagePayloadDirty(messageId: string): Promise<void>;
messagePayload(messageId: string): Promise<MessagePayload>;
/**
*
* Room Invitation
*
*/
abstract roomInvitationAccept(roomInvitationId: string): Promise<void>;
protected abstract roomInvitationRawPayload(roomInvitationId: string): Promise<any>;
protected abstract roomInvitationRawPayloadParser(rawPayload: any): Promise<RoomInvitationPayload>;
roomInvitationPayload(roomInvitationId: string): Promise<RoomInvitationPayload>;
/**
*
* Room
*
*/
abstract roomAdd(roomId: string, contactId: string): Promise<void>;
abstract roomAvatar(roomId: string): Promise<FileBox>;
abstract roomCreate(contactIdList: string[], topic?: string): Promise<string>;
abstract roomDel(roomId: string, contactId: string): Promise<void>;
abstract roomQuit(roomId: string): Promise<void>;
abstract roomTopic(roomId: string): Promise<string>;
abstract roomTopic(roomId: string, topic: string): Promise<void>;
abstract roomTopic(roomId: string, topic?: string): Promise<string | void>;
abstract roomQrcode(roomId: string): Promise<string>;
abstract roomList(): Promise<string[]>;
abstract roomMemberList(roomId: string): Promise<string[]>;
protected abstract roomRawPayload(roomId: string): Promise<any>;
protected abstract roomRawPayloadParser(rawPayload: any): Promise<RoomPayload>;
protected abstract roomMemberRawPayload(roomId: string, contactId: string): Promise<any>;
protected abstract roomMemberRawPayloadParser(rawPayload: any): Promise<RoomMemberPayload>;
abstract roomAnnounce(roomId: string): Promise<string>;
abstract roomAnnounce(roomId: string, text: string): Promise<void>;
roomMemberSearch(roomId: string, query: (YOU | string) | RoomMemberQueryFilter): Promise<string[]>;
roomSearch(query?: RoomQueryFilter): Promise<string[]>;
protected roomQueryFilterFactory(query: RoomQueryFilter): RoomPayloadFilterFunction;
/**
* Check a Room Id if it's still valid.
* For example: talk to the server, and see if it should be deleted in the local cache.
*/
roomValidate(roomId: string): Promise<boolean>;
protected roomPayloadCache(roomId: string): undefined | RoomPayload;
protected roomPayloadDirty(roomId: string): Promise<void>;
roomPayload(roomId: string): Promise<RoomPayload>;
/**
* Concat roomId & contactId to one string
*/
private cacheKeyRoomMember;
protected roomMemberPayloadDirty(roomId: string): Promise<void>;
roomMemberPayload(roomId: string, contactId: string): Promise<RoomMemberPayload>;
}
export default Puppet;