@juzi/wechaty
Version:
Wechaty is a RPA SDK for Chatbot Makers.
392 lines • 15.4 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 type { SayableSayer, Sayable, SayOptionsObject } from '../sayable/mod.js';
import type { MessageInterface } from './message.js';
import type { TagInterface } from './tag.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, ContactImplInterface> | undefined;
readonly pool: Map<string, ContactImplInterface>;
load<L extends import("clone-class/dist/esm/src/constructor.js").ClassInterface<{}> & {
new (...args: any[]): ContactImplInterface;
prototype: ContactImplInterface;
} & import("../user-mixins/poolify.js").PoolifyMixin<ContactImplInterface>>(this: L, id: string): ContactImplInterface;
}) & (new () => import("typed-emitter").default<import("../schemas/contact-events.js").ContactEventListeners>);
/**
* All wechat contacts(friend) will be encapsulated as a Contact.
* [Examples/Contact-Bot]{@link https://github.com/wechaty/wechaty/blob/1523c5e02be46ebe2cc172a744b2fbe53351540e/examples/contact-bot.ts}
*
* @property {string} id - Get Contact id.
* This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table)
*/
declare class ContactMixin extends MixinBase implements SayableSayer {
readonly id: string;
static Type: typeof PUPPET.types.Contact;
static Gender: typeof PUPPET.types.ContactGender;
/**
* The way to search Contact
*
* @typedef ContactQueryFilter
* @property {string} name - The name-string set by user-self, should be called name
* @property {string} alias - The name-string set by bot for others, should be called alias
* [More Detail]{@link https://github.com/wechaty/wechaty/issues/365}
*/
/**
* Try to find a contact by filter: {name: string | RegExp} / {alias: string | RegExp}
*
* Find contact by name or alias, if the result more than one, return the first one.
*
* @static
* @param {string | ContactQueryFilter} query `string` will search `name` & `alias`
* @returns {(Promise<undefined | ContactInterface>)} If can find the contact, return Contact, or return null
* @example
* const bot = new Wechaty()
* await bot.start()
* const contactFindByName = await bot.Contact.find({ name:"ruirui"} )
* const contactFindByAlias = await bot.Contact.find({ alias:"lijiarui"} )
*/
static find(query: string | PUPPET.filters.Contact): Promise<undefined | ContactInterface>;
/**
* Find contact by `name` or `alias`
*
* If use Contact.findAll() get the contact list of the bot.
*
* #### definition
* - `name` the name-string set by user-self, should be called name
* - `alias` the name-string set by bot for others, should be called alias
*
* @static
* @param {string | ContactQueryFilter} [queryArg] `string` will search `name` & `alias`
* @returns {Promise<ContactInterface[]>}
* @example
* const bot = new Wechaty()
* await bot.start()
* const contactList = await bot.Contact.findAll() // get the contact list of the bot
* const contactList = await bot.Contact.findAll({ name: 'ruirui' }) // find all of the contacts whose name is 'ruirui'
* const contactList = await bot.Contact.findAll({ alias: 'lijiarui' }) // find all of the contacts whose alias is 'lijiarui'
*/
static findAll(query?: string | PUPPET.filters.Contact): Promise<ContactInterface[]>;
static batchLoadContacts(contactIdList: string[]): Promise<ContactInterface[]>;
static delete(contact: ContactInterface): Promise<void>;
/**
*
* Instance properties
* @ignore
*
*/
payload?: PUPPET.payloads.Contact;
/**
* @hideconstructor
*/
constructor(id: string);
/**
* @ignore
*/
toString(): string;
/**
* > Tips:
* This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table)
*
* @param {(string | ContactInterface | FileBox | UrlLink | MiniProgram | Location)} sayable
* send text, Contact, or file to contact. </br>
* You can use {@link https://www.npmjs.com/package/file-box|FileBox} to send file
* @returns {Promise<void | MessageInterface>}
* @example
* const bot = new Wechaty()
* await bot.start()
* const contact = await bot.Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any of your contact name in wechat
*
* // 1. send text to contact
*
* await contact.say('welcome to wechaty!')
* const msg = await contact.say('welcome to wechaty!') // only supported by puppet-padplus
*
* // 2. send media file to contact
*
* import { FileBox } from 'wechaty'
* const fileBox1 = FileBox.fromUrl('https://wechaty.github.io/wechaty/images/bot-qr-code.png')
* const fileBox2 = FileBox.fromFile('/tmp/text.txt')
* await contact.say(fileBox1)
* const msg1 = await contact.say(fileBox1) // only supported by puppet-padplus
* await contact.say(fileBox2)
* const msg2 = await contact.say(fileBox2) // only supported by puppet-padplus
*
* // 3. send contact card to contact
*
* const contactCard = bot.Contact.load('contactId')
* const msg = await contact.say(contactCard) // only supported by puppet-padplus
*
* // 4. send url link to contact
*
* const urlLink = new UrlLink ({
* description : 'WeChat Bot SDK for Individual Account, Powered by TypeScript, Docker, and Love',
* thumbnailUrl: 'https://avatars0.githubusercontent.com/u/25162437?s=200&v=4',
* title : 'Welcome to Wechaty',
* url : 'https://github.com/wechaty/wechaty',
* })
* await contact.say(urlLink)
* const msg = await contact.say(urlLink) // only supported by puppet-padplus
*
* // 5. send mini program to contact
*
* const miniProgram = new MiniProgram ({
* username : 'gh_xxxxxxx', //get from mp.weixin.qq.com
* appid : '', //optional, get from mp.weixin.qq.com
* title : '', //optional
* pagepath : '', //optional
* description : '', //optional
* thumbnailurl : '', //optional
* })
* await contact.say(miniProgram)
* const msg = await contact.say(miniProgram) // only supported by puppet-padplus
*
* // 6. send location to contact
* const location = new Location ({
* accuracy : 15,
* address : '北京市北京市海淀区45 Chengfu Rd',
* latitude : 39.995120999999997,
* longitude : 116.334154,
* name : '东升乡人民政府(海淀区成府路45号)',
* })
* await contact.say(location)
* const msg = await contact.say(location)
*/
say(sayable: Sayable, options?: SayOptionsObject): Promise<void | MessageInterface>;
/**
* Get the name from a contact
*
* @returns {string}
* @example
* const name = contact.name()
*/
name(): string;
aka(): string;
realName(): string;
alias(): Promise<undefined | string>;
alias(newAlias: string): Promise<void>;
alias(empty: null): Promise<void>;
/**
* GET / SET / DELETE the phone list for a contact
*
* @param {(none | string[])} phoneList
* @returns {(Promise<string[] | void>)}
* @example <caption> GET the phone list for a contact, return {(Promise<string[]>)}</caption>
* const phoneList = await contact.phone()
* if (phone.length === 0) {
* console.log('You have not yet set any phone number for contact ' + contact.name())
* } else {
* console.log('You have already set phone numbers for contact ' + contact.name() + ':' + phoneList.join(','))
* }
*
* @example <caption>SET the phoneList for a contact</caption>
* try {
* const phoneList = ['13999999999', '13888888888']
* await contact.alias(phoneList)
* console.log(`change ${contact.name()}'s phone successfully!`)
* } catch (e) {
* console.log(`failed to change ${contact.name()} phone!`)
* }
*/
phone(): Promise<string[]>;
phone(phoneList: string[]): Promise<void>;
corporation(): Promise<undefined | string>;
corporation(remark: string | null): Promise<void>;
description(): Promise<undefined | string>;
description(newDescription: string | null): Promise<void>;
title(): string | null;
coworker(): boolean;
/**
* Check if contact is friend
*
* > 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 {boolean | null}
*
* <br>True for friend of the bot <br>
* False for not friend of the bot, null for unknown.
* @example
* const isFriend = contact.friend()
*/
friend(): undefined | boolean;
/**
* Enum for ContactType
* @enum {number}
* @property {number} Unknown - ContactType.Unknown (0) for Unknown
* @property {number} Personal - ContactType.Personal (1) for Personal
* @property {number} Official - ContactType.Official (2) for Official
*/
/**
* Return the type of the Contact
* > Tips: ContactType is enum here.</br>
* @returns {ContactType.Unknown | ContactType.Personal | ContactType.Official}
*
* @example
* const bot = new Wechaty()
* await bot.start()
* const isOfficial = contact.type() === bot.Contact.Type.Official
*/
type(): PUPPET.types.Contact;
/**
* @ignore
* TODO: Check if the contact is star contact.
*
* @returns {boolean | null} - True for star friend, False for no star friend.
* @example
* const isStar = contact.star()
*/
star(): undefined | boolean;
/**
* Contact gender
* > Tips: ContactGender is enum here. </br>
*
* @returns {ContactGender.Unknown | ContactGender.Male | ContactGender.Female}
* @example
* const gender = contact.gender() === bot.Contact.Gender.Male
*/
gender(): PUPPET.types.ContactGender;
/**
* Get the region 'province' from a contact
*
* @returns {string | null}
* @example
* const province = contact.province()
*/
province(): undefined | string;
/**
* Get the region 'city' from a contact
*
* @returns {string | null}
* @example
* const city = contact.city()
*/
city(): undefined | string;
/**
* Get avatar picture file stream
*
* @returns {Promise<FileBox>}
* @example
* // Save avatar to local file like `1-name.jpg`
*
* const file = await contact.avatar()
* const name = file.name
* await file.toFile(name, true)
* console.log(`Contact: ${contact.name()} with avatar file: ${name}`)
*/
avatar(): Promise<FileBoxInterface>;
/**
* Get all tags of contact
*
* @returns {Promise<TagInterface[]>}
* @example
* const tags = await contact.tags()
*/
tags(): Promise<TagInterface[]>;
/**
* Add a Tag
*/
tag(tags: TagInterface | TagInterface[]): Promise<void>;
/**
* Remove a Tag
*/
tagRemove(tags: TagInterface | TagInterface[]): Promise<void>;
/**
* Force reload data for Contact, Sync data from low-level API again.
*
* @returns {Promise<this>}
* @example
* await contact.sync()
*/
sync(): Promise<void>;
/**
* `ready()` is For FrameWork 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>;
readMark(hasRead: boolean): Promise<void>;
readMark(): Promise<boolean>;
/**
* @ignore
*/
isReady(): boolean;
/**
* Check if contact is self
*
* @returns {boolean} True for contact is self, False for contact is others
* @example
* const isSelf = contact.self()
*/
self(): boolean;
/**
* Get the handle from a contact.
*
* > A Twitter handle is the username that appears at the end of your unique Twitter URL.
*
* Sometimes cannot get handle due to the puppet implementation.
*
* @ignore
* @returns {string | null}
* @example
* const handle = contact.handle()
*/
handle(): undefined | string;
/**
* Huan(202203): `weixin()` will be removed in v2.0
* @link https://github.com/wechaty/puppet/issues/181
* @deprecated use `handle()` instead
*/
weixin(): undefined | string;
additionalInfo(): undefined | any;
payloadModify(payload: Partial<PUPPET.payloads.Contact>): Promise<void>;
}
declare const ContactImplBase_base: {
new (...args: any[]): {};
valid: (o: any) => o is ContactImplInterface;
validInstance: (target: any) => target is ContactMixin;
validInterface: (target: any) => target is ContactImplInterface;
} & typeof ContactMixin;
declare class ContactImplBase extends ContactImplBase_base {
}
interface ContactImplInterface extends ContactImplBase {
}
declare type ContactProtectedProperty = 'ready';
declare type ContactInterface = Omit<ContactImplInterface, ContactProtectedProperty>;
declare const ContactImpl_base: {
new (...args: any[]): {};
valid: (o: any) => o is ContactInterface;
validInstance: (target: any) => target is ContactImplBase;
validInterface: (target: any) => target is ContactInterface;
} & typeof ContactImplBase;
declare class ContactImpl extends ContactImpl_base {
}
declare type ContactConstructor = Constructor<ContactImplInterface, Omit<typeof ContactImpl, 'load' | 'batchLoadContacts'>>;
export type { ContactConstructor, ContactProtectedProperty, ContactInterface, };
export { ContactImpl, };
//# sourceMappingURL=contact.d.ts.map