@kotori-bot/core 1.7.1 → 1.7.2

package/lib/components/api.d.ts

@@ -0,0 +1,420 @@
+import type { ChannelInfoResponse, GetFileDataResponse, GetFilePathResponse, GetFileUrlResponse, GroupInfoResponse, GuildInfoResponse, Message, SelfInfoResponse, SendMessageResponse, UploadFileResponse, UserInfoResponse } from '../types';
+import type { EventsMapping } from '../types/events';
+import type Adapter from './adapter';
+import type { Session } from './session';
+type ReverseList = {
+    [K in keyof EventsMapping]: Parameters<EventsMapping[K]>[0] extends Session ? K : never;
+};
+type SessionEvents = ReverseList[keyof ReverseList];
+type Actions = Exclude<keyof Api, 'adapter' | 'getSupportedEvents' | 'getSupportedEvents'>;
+/**
+ * Api which identify bot's standard platform apis.
+ *
+ * For different `api` child class, not most of them have implementation.
+ *
+ * @class
+ * @abstract
+ */
+export declare abstract class Api {
+    /**
+     * Get supported actions for current api implementation.
+     *
+     * @returns Supported actions
+     */
+    getSupportedActions(): Actions[];
+    abstract getSupportedEvents(): SessionEvents[];
+    /**
+     * Current api's bot instance.
+     *
+     * @readonly
+     */
+    readonly adapter: Adapter<any, any, any>;
+    /**
+     * Api class constructor.
+     *
+     * @param adapter - Current api's bot instance
+     */
+    constructor(adapter: Adapter<any, any, any>);
+    /**
+     * Send a private message.
+     *
+     * @param message - Message content to send
+     * @param userId - Target user id
+     * @param meta - Extra meta data, optional
+     * @returns Message id and send time
+     *
+     * @async
+     */
+    sendPrivateMsg(message: Message, userId: string, meta?: object): Promise<SendMessageResponse>;
+    /**
+     * Send a group message.
+     *
+     * @param message - Message content to send
+     * @param groupId - Target group id
+     * @param meta - Extra meta data, optional
+     * @returns Message id and send time
+     *
+     * @async
+     */
+    sendGroupMsg(message: Message, groupId: string, meta?: object): Promise<SendMessageResponse>;
+    /**
+     * Send a channel message.
+     *
+     * @param message - Message content to send
+     * @param guildId - Target guild id
+     * @param channelId - Target channel id
+     * @param meta - Extra meta data, optional
+     * @returns Message id and send time
+     *
+     * @async
+     */
+    sendChannelMsg(message: Message, guildId: string, channelId: string, meta?: object): Promise<SendMessageResponse>;
+    /**
+     * Delete a message.
+     *
+     * Required target message that is sent by self or bot had manger permission.
+     *
+     * @param messageId - Target message id
+     * @param meta - Extra meta data, optional
+     *
+     * @async
+     */
+    deleteMsg(messageId: string, meta?: object): void;
+    /**
+     * Get information about the bot itself.
+     *
+     * @returns Self info
+     *
+     * @async
+     */
+    getSelfInfo(meta?: object): Promise<SelfInfoResponse>;
+    /**
+     * Get user information.
+     *
+     * @param userId - Target user id, can be the friend or the stronger
+     * @param meta - Extra meta data, optional
+     * @returns User info
+     *
+     * @async
+     */
+    getUserInfo(userId: string, meta?: object): Promise<UserInfoResponse>;
+    /**
+     * Get friend list.
+     *
+     * @param meta - Extra meta data, optional
+     * @returns Friend list information
+     *
+     * @async
+     */
+    getFriendList(meta?: object): Promise<UserInfoResponse[]>;
+    /**
+     * Get group information.
+     *
+     * @param groupId - Target group id
+     * @param meta - Extra meta data, optional
+     * @returns Group info
+     *
+     * @async
+     */
+    getGroupInfo(groupId: string, meta?: object): Promise<GroupInfoResponse>;
+    /**
+     * Get group list.
+     *
+     * @param meta - Extra meta data, optional
+     * @returns Group list information
+     *
+     * @async
+     */
+    getGroupList(meta?: object): Promise<GroupInfoResponse[]>;
+    /**
+     * Get group member information.
+     *
+     * @param groupId - Target group id
+     * @param userId - Target user id
+     * @param meta - Extra meta data, optional
+     * @returns Group member info
+     *
+     * @async
+     */
+    getGroupMemberInfo(groupId: string, userId: string, meta?: object): Promise<SelfInfoResponse>;
+    /**
+     * Get group member list.
+     *
+     * @param groupId - Target group id
+     * @param meta - Extra meta data, optional
+     * @returns Group member list information
+     *
+     * @async
+     */
+    getGroupMemberList(groupId: string, meta?: object): Promise<SelfInfoResponse[]>;
+    /**
+     * Set group information.
+     *
+     * @param groupId - Target group id
+     * @param groupName - Group name
+     * @param meta - Extra meta data, optional
+     */
+    setGroupName(groupId: string, groupName: string, meta?: object): void;
+    /**
+     * Leave a group, if bot is owner so it will be destroy the group.
+     *
+     * @param groupId - Target group id
+     * @param meta - Extra meta data, optional
+     */
+    leaveGroup(groupId: string, meta?: object): void;
+    /**
+     * Get guild information.
+     *
+     * @param guildId - Target guild id
+     * @param meta - Extra meta data, optional
+     * @returns Guild info
+     *
+     * @async
+     */
+    getGuildInfo(guildId: string, meta?: object): Promise<GuildInfoResponse>;
+    /**
+     * Get guild list.
+     *
+     * @param meta - Extra meta data, optional
+     * @returns Guild list information
+     *
+     * @async
+     */
+    getGuildList(meta?: object): Promise<GuildInfoResponse[]>;
+    /**
+     * Set guild information.
+     *
+     * @param guildId - Target guild id
+     * @param guildName - Guild name
+     * @param meta - Extra meta data, optional
+     */
+    setGuildName(guildId: string, guildName: string, meta?: object): void;
+    /**
+     * Get guild member information.
+     *
+     * @param guildId - Target guild id
+     * @param channelId - Target channel id
+     * @param userId - Target user id
+     * @param meta - Extra meta data, optional
+     * @returns Guild member info
+     *
+     * @async
+     */
+    getGuildMemberInfo(guildId: string, userId: string, meta?: object): Promise<UserInfoResponse>;
+    /**
+     * Get guild member list.
+     *
+     * @param guildId - Target guild id
+     * @param channelId - Target channel id
+     * @param meta - Extra meta data, optional
+     * @returns Guild member list information
+     *
+     * @async
+     */
+    getGuildMemberList(guildId: string, meta?: object): Promise<UserInfoResponse[]>;
+    /**
+     * Leave a guild.
+     *
+     * @param guildId - Target guild id
+     * @param meta - Extra meta data, optional
+     */
+    leaveGuild(guildId: string, meta?: object): void;
+    /**
+     * Get channel information.
+     *
+     * @param guildId - Target guild id
+     * @param channelId - Target channel id
+     * @param meta - Extra meta data, optional
+     * @returns Channel info
+     *
+     * @async
+     */
+    getChannelInfo(guildId: string, channelId: string, meta?: object): Promise<ChannelInfoResponse>;
+    /**
+     * Get channel list.
+     *
+     * @param guildId - Target guild id
+     * @param joinedOnly - Whether to get joined channels only, default is false
+     * @param meta - Extra meta data, optional
+     * @returns Channel list information
+     *
+     * @async
+     */
+    getChannelList(guildId: string, joinedOnly?: boolean, meta?: object): Promise<ChannelInfoResponse[]>;
+    /**
+     * Set channel information.
+     *
+     * @param guildId - Target guild id
+     * @param channelId - Target channel id
+     * @param channelName - Channel name
+     * @param meta - Extra meta data, optional
+     */
+    setChannelName(guildId: string, channelId: string, channelName: string, meta?: object): void;
+    /**
+     * Get channel member information.
+     *
+     * @param guildId - Target guild id
+     * @param channelId - Target channel id
+     * @param userId - Target user id
+     * @param meta - Extra meta data, optional
+     * @returns Channel member info
+     *
+     * @async
+     */
+    getChannelMemberInfo(guildId: string, channelId: string, userId: string, meta?: object): Promise<UserInfoResponse>;
+    /**
+     * Get channel member list.
+     *
+     * @param guildId - Target guild id
+     * @param channelId - Target channel id
+     * @param meta - Extra meta data, optional
+     * @returns Channel member list information
+     *
+     * @async
+     */
+    getChannelMemberList(guildId: string, channelId: string, meta?: object): Promise<UserInfoResponse[]>;
+    /**
+     * Leave a channel.
+     *
+     * @param guildId - Target guild id
+     * @param channelId - Target channel id
+     * @param meta - Extra meta data, optional
+     */
+    leaveChannel(guildId: string, channelId: string, meta?: object): void;
+    /**
+     * Upload file from url.
+     *
+     * @param name - File name
+     * @param url - File url
+     * @param headers - File download url headers, optional
+     * @param meta - Extra meta data, optional
+     * @returns File id
+     *
+     * @async
+     */
+    uploadFileUrl(name: string, url: string, headers?: Record<string, string>, meta?: object): Promise<UploadFileResponse>;
+    /**
+     * Upload file from path.
+     *
+     * @param name - File name
+     * @param path - File path
+     * @param meta - Extra meta data, optional
+     * @returns File id
+     *
+     * @async
+     */
+    uploadFilePath(name: string, path: string, meta?: object): Promise<UploadFileResponse>;
+    /**
+     * Upload file from data.
+     *
+     * @param name - File name
+     * @param data - File data
+     * @param meta - Extra meta data, optional
+     * @returns File id
+     *
+     * @async
+     */
+    uploadFileData(name: string, data: Buffer, meta?: object): Promise<UploadFileResponse>;
+    /**
+     * Get file url.
+     *
+     * @param filedId - File id
+     * @param meta - Extra meta data, optional
+     * @returns File url data
+     *
+     * @async
+     */
+    getFileUrl(filedId: string, meta?: object): Promise<GetFileUrlResponse>;
+    /**
+     * Get file path.
+     *
+     * @param filedId - File id
+     * @param meta - Extra meta data, optional
+     * @returns File path data
+     *
+     * @async
+     */
+    getFilePath(filedId: string, meta?: object): Promise<GetFilePathResponse>;
+    /**
+     * Get file data.
+     *
+     * @param filedId - File id
+     * @param meta - Extra meta data, optional
+     * @returns File data
+     *
+     * @async
+     */
+    getFileData(filedId: string, meta?: object): Promise<GetFileDataResponse>;
+    /**
+     * Set group avatar.
+     *
+     * @param groupId - Target group id
+     * @param image - Image data
+     * @param meta - Extra meta data, optional
+     *
+     * @experimental
+     */
+    setGroupAvatar(groupId: string, image: string, meta?: object): void;
+    /**
+     * Set group admin.
+     *
+     * @param groupId - Target group id
+     * @param userId - Target user id
+     * @param enable - Whether to set admin
+     * @param meta - Extra meta data, optional
+     *
+     * @experimental
+     */
+    setGroupAdmin(groupId: string, userId: string, enable: boolean, meta?: object): void;
+    /**
+     * Set group card.
+     *
+     * @param groupId - Target group id
+     * @param userId - Target user id
+     * @param card - Card content
+     * @param meta - Extra meta data, optional
+     *
+     * @experimental
+     */
+    setGroupCard(groupId: string, userId: string, card: string, meta?: object): void;
+    /**
+     * Set group members ban or unban.
+     *
+     * @param groupId - Target group id
+     * @param userId - Target user id
+     * @param time - Ban time, 0 means unban
+     * @param meta - Extra meta data, optional
+     *
+     * @experimental
+     */
+    setGroupBan(groupId: string, userId: string, time: number, meta?: object): void;
+    /**
+     * Set group new notice.
+     *
+     * @param groupId - Target group id
+     * @param content - Notice content
+     * @param image - Notice image, optional
+     * @param meta - Extra meta data, optional
+     *
+     * @experimental
+     */
+    sendGroupNotice(groupId: string, content: string, image?: string, meta?: object): void;
+    /**
+     * Set group whole ban
+     *
+     * @param groupId - Target group id
+     * @param enable - Whether to ban
+     */
+    setGroupWholeBan(groupId: string, enable?: boolean): void;
+    /**
+     * Set group members kicked.
+     *
+     * @param groupId - Target group id
+     * @param userId - Target user id
+     * @param meta - Extra meta data, optional
+     *
+     * @experimental
+     */
+    setGroupKick(groupId: string, userId: string, meta?: object): void;
+}
+export default Api;

package/lib/components/api.js

@@ -1,11 +1,11 @@
 /**
 * @Package @kotori-bot/core
-* @Version 1.7.1
+* @Version 1.7.2
 * @Author Arimura Sena <me@hotaru.icu>
 * @Copyright 2024-2025 Hotaru. All rights reserved.
 * @License GPL-3.0
 * @Link https://github.com/kotorijs/kotori
-* @Date 2026/2/14 00:45:33
+* @Date 2026/2/14 15:50:13
 */
 "use strict";
 var __defProp = Object.defineProperty;
@@ -48,14 +48,14 @@ class Api {
    *
    * @readonly
    */
-  // biome-ignore lint:
+  // biome-ignore lint: *
   adapter;
   /**
    * Api class constructor.
    *
    * @param adapter - Current api's bot instance
    */
-  // biome-ignore lint:
+  // biome-ignore lint: *
   constructor(adapter) {
     this.adapter = adapter;
   }

package/lib/components/cache.d.ts

@@ -0,0 +1,37 @@
+import { type Context, Service } from '../app';
+type CacheKey = string | symbol | number;
+type CacheValue = string | number | object;
+type Container = Map<CacheKey, CacheValue>;
+/**
+ * Cache service
+ *
+ * @class
+ * @extends Service
+ */
+export declare class Cache extends Service {
+    private cache?;
+    constructor(ctx: Context);
+    start(): void;
+    stop(): void;
+    /**
+     * Get the container of current content instance.
+     *
+     * @returns THe container
+     */
+    getContainer(): Container;
+    /**
+     * Get the value from current the container.
+     *
+     * @param prop The property name
+     * @returns The value
+     */
+    get<T = CacheValue>(prop: CacheKey): T;
+    /**
+     * Set the value to current the container.
+     *
+     * @param prop The property name
+     * @param value The value
+     */
+    set(prop: CacheKey, value: CacheValue): void;
+}
+export default Cache;

package/lib/components/cache.js

@@ -1,11 +1,11 @@
 /**
 * @Package @kotori-bot/core
-* @Version 1.7.1
+* @Version 1.7.2
 * @Author Arimura Sena <me@hotaru.icu>
 * @Copyright 2024-2025 Hotaru. All rights reserved.
 * @License GPL-3.0
 * @Link https://github.com/kotorijs/kotori
-* @Date 2026/2/14 00:45:33
+* @Date 2026/2/14 15:50:13
 */
 "use strict";
 var __defProp = Object.defineProperty;
@@ -31,8 +31,8 @@ __export(cache_exports, {
   default: () => cache_default
 });
 module.exports = __toCommonJS(cache_exports);
-var import_error = require("../utils/error");
 var import_app = require("../app");
+var import_error = require("../utils/error");
 class Cache extends import_app.Service {
   cache = /* @__PURE__ */ new Map();
   constructor(ctx) {

package/lib/components/command.d.ts

@@ -0,0 +1,153 @@
+import { type ArgsOrigin, type CommandAction, type CommandArgType, type CommandArgTypeSign, type CommandConfig, type OptsOrigin, UserAccess } from '../types';
+import { CommandError } from '../utils/error';
+/** Command argument */
+interface CommandArg {
+    /** Argument displayname */
+    name: string;
+    /** Argument type */
+    type: CommandArgTypeSign;
+    /** Argument is wether optional */
+    optional: boolean;
+    /** Argument default value, if exists so `optional` is true */
+    default?: CommandArgType;
+    /** Argument is wether rest arguments */
+    rest: boolean;
+}
+/** Command option */
+interface CommandOption {
+    /** Option short name, composed a uppercase letter */
+    name: string;
+    /** Option type */
+    type: CommandArgTypeSign;
+    /** Option full name (real name), composed some lowercase letters and connect by `-` between word and word */
+    realname: string;
+    /** Option description */
+    description?: string;
+}
+/**
+ * Command meta data.
+ *
+ * @template Args - Command arguments
+ * @template Opts - Command options
+ */
+interface CommandData<Args = ArgsOrigin, Opts = OptsOrigin, Scope = 'all'> {
+    /** Command root content */
+    root: string;
+    /** Command alias (need bring command prefix) */
+    alias: string[];
+    /** Command shortcut (needn't bring command prefix) */
+    shortcut: string[];
+    /** Command is wether hide at the menu */
+    hide: boolean;
+    /** Command arguments */
+    args: CommandArg[];
+    /** Command options */
+    options: CommandOption[];
+    /** Command require message scope (session type) */
+    scope: CommandConfig['scope'];
+    /** Command require user access level */
+    access: UserAccess;
+    /** Command description */
+    description?: string;
+    /** Command help message, it has more details than `description` */
+    help?: string;
+    /** Command action */
+    action?: CommandAction<Args, Opts, Scope>;
+}
+type GetSignType<T extends string> = T extends `${string}number${string}` ? number : T extends `${string}boolean${string}` ? boolean : string;
+type GetArgCtn<Template extends string> = Template extends `${string}:${infer Suffix}` ? Suffix extends `${infer T}=${string}` ? GetSignType<T> : GetSignType<Suffix> : Template extends `${infer T}=${string}` ? GetSignType<T> : string;
+type ParseArgs<Template extends string> = string extends Template ? ArgsOrigin : Template extends `${string} ${`<${infer Ctn}>`}${infer Rest}` ? Ctn extends `...${infer Ctn2}` ? [...GetSignType<Ctn2>[]] : [GetArgCtn<Ctn>, ...ParseArgs<Rest>] : Template extends `${string} [${infer Ctn}]${infer Rest}` ? Ctn extends `${infer Ctn2}=${string}` ? Ctn2 extends `...${infer Ctn3}` ? [...GetSignType<Ctn3>[]] : [GetArgCtn<Ctn2>, ...ParseArgs<Rest>] : Ctn extends `...${infer Ctn2}` ? [...GetSignType<Ctn2>[]] : [GetArgCtn<Ctn>?, ...ParseArgs<Rest>] : [];
+type ParseOpts<Template extends string> = string extends Template ? {} : Template extends `${infer K}:${infer V}` ? GetSignType<V> extends boolean ? {
+    [C in K]: GetSignType<V>;
+} : {
+    [C in K]?: GetSignType<V>;
+} : {};
+/**
+ * Command.
+ *
+ * @template Template - Command template
+ * @template Opts - Command options
+ *
+ * @class
+ */
+export declare class Command<Template extends string = string, Opts extends OptsOrigin = OptsOrigin, Scope extends CommandConfig['scope'] | 'all' = 'all'> {
+    private static handleDefaultValue;
+    private static parseArgs;
+    static run(input: string, data: CommandData): CommandError | {
+        args: ArgsOrigin;
+        options: OptsOrigin;
+    };
+    private template;
+    /**
+     * Command meta data.
+     *
+     * @readonly
+     */
+    readonly meta: CommandData<ParseArgs<Template>, Opts, Scope>;
+    /**
+     * Create a command instance
+     *
+     * @param template - Command template.
+     * @param config - Command config.
+     */
+    constructor(template: Template, config?: CommandConfig);
+    private parse;
+    /**
+     * Add command alias.
+     *
+     * @param alias - Command alias.
+     * @returns Command instance
+     */
+    alias(alias: string | string[]): this;
+    /**
+     * Add command shortcut.
+     *
+     * @param short - shortcut name
+     * @returns Command instance
+     */
+    shortcut(short: string | string[]): this;
+    /**
+     * Set the message scope which command require.
+     *
+     * @param scope - Message scope.
+     * @returns Command instance
+     */
+    scope<S extends CommandConfig['scope']>(scope: S): Command<Template, Opts, S>;
+    /**
+     * Set the user access level which command require.
+     *
+     * @param access - User access level.
+     * @returns Command instance
+     */
+    access(access: UserAccess): this;
+    /**
+     * Add command option.
+     *
+     * @param name - Option name.
+     * @param template - Option template.
+     * @returns Command instance
+     */
+    option<TemplateOpt extends string>(name: string, template: TemplateOpt): Command<Template, Opts & ParseOpts<TemplateOpt>>;
+    /**
+     * Set command action.
+     *
+     * @param callback - Command action.
+     * @returns Command instance
+     */
+    action(callback: CommandAction<ParseArgs<Template>, Opts, Scope>): this;
+    /**
+     * Set command help text.
+     *
+     * @param text - Command help text.
+     * @returns Command instance
+     */
+    help(text: string): this;
+    /**
+     * Set command hide.
+     *
+     * @param isHide - Command hide.
+     * @returns Command instance
+     */
+    hide(isHide?: boolean): this;
+}
+export default Command;

package/lib/components/command.js

@@ -1,11 +1,11 @@
 /**
 * @Package @kotori-bot/core
-* @Version 1.7.1
+* @Version 1.7.2
 * @Author Arimura Sena <me@hotaru.icu>
 * @Copyright 2024-2025 Hotaru. All rights reserved.
 * @License GPL-3.0
 * @Link https://github.com/kotorijs/kotori
-* @Date 2026/2/14 00:45:33
+* @Date 2026/2/14 15:50:13
 */
 "use strict";
 var __create = Object.create;