@webx-ui/module-notifications 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 webx-ui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# @webx-ui/module-notifications
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The front end of the Notifications section of the [WebX UI](https://github.com/webx-ui/webx-ui)
+admin panel: channels to Telegram and e-mail, their Mustache templates in every language of the
+site, a live preview, tests, and the log of every delivery.
+
+The other half is the Composer package `webx-ui/module-notifications`, which owns the channels, the
+providers, the queue, the API and the agent tools. A section appears in the panel when both halves
+are installed.
+
+## Install
+
+```bash
+npm install @webx-ui/module-notifications
+```
+
+```ts
+import { createAdmin } from '@webx-ui/module-admin'
+import { notifications } from '@webx-ui/module-notifications'
+import '@webx-ui/module-notifications/style.css'
+
+createAdmin({
+  basePath: '/cms',
+  modules: [notifications()],
+}).mount()
+```
+
+`php artisan webx:module:add notifications` installs both halves and writes this into the panel's
+entry. `notifications({ path: '/alerts' })` puts the section somewhere else inside the panel.
+
+## What is in it
+
+- The section: channels with their switch, copy and bin; the delivery log with filters and
+  «Send again».
+- A channel's page: the described screen `notifications.channel` with the provider's settings, the
+  template in `WxCodeEditor` with Mustache highlighted and suggested after `{{`, and the preview
+  beside it — rendered by `renderMessage()`, held to the server's render by shared test cases.
+- Node types for screens: `wx-notifications-template`, `wx-notifications-chats`,
+  `wx-notifications-emails`, and `wx-notifications-channels` — the picker a module chooses its
+  channels for an event with, also exported as `WxNotificationChannelsField`.
+
+The guide: https://webx-ui.github.io/webx-ui/guide/notifications

package/dist/ChannelPage.d.ts

@@ -0,0 +1,19 @@
+/**
+ * One channel (§10.3): the described screen `notifications.channel` — the common part and the
+ * provider's settings the server lays over it — with the live preview beside it on a wide pane and
+ * under it on a narrow one, and one explicit save.
+ *
+ * A secret is never in the form: the server answers which are set, and the field says so with
+ * `••••••••` until a new one is typed. "Forget" is in the head's menu, one per secret that is set,
+ * and takes effect on the save, like every other change here.
+ *
+ * The form's values are what "Check", "Send a test" and the preview run on — saved or not: a
+ * channel is tried before it is kept, and a test of a switched-off channel is the point of one.
+ */
+type __VLS_Props = {
+    base?: string;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    base: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/ChannelsField.d.ts

@@ -0,0 +1,23 @@
+type __VLS_Props = {
+    /** The event the channels are for: `inbox.submission`. */
+    event: string;
+    disabled?: boolean;
+    /** Where the section is in the panel, for the link to it. */
+    base?: string;
+    addText?: string;
+    emptyText?: string;
+};
+type __VLS_PublicProps = {
+    modelValue?: number[] | null;
+} & __VLS_Props;
+declare const _default: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:modelValue": (value: number[] | null) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:modelValue"?: ((value: number[] | null) => any) | undefined;
+}>, {
+    disabled: boolean;
+    base: string;
+    emptyText: string;
+    addText: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/ChatsField.d.ts

@@ -0,0 +1,15 @@
+import { ChatRecipient } from './types';
+type __VLS_Props = {
+    disabled?: boolean;
+};
+type __VLS_PublicProps = {
+    modelValue?: ChatRecipient[] | null;
+} & __VLS_Props;
+declare const _default: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:modelValue": (value: ChatRecipient[] | null) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:modelValue"?: ((value: ChatRecipient[] | null) => any) | undefined;
+}>, {
+    disabled: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/EmailsField.d.ts

@@ -0,0 +1,15 @@
+import { EmailRecipient } from './types';
+type __VLS_Props = {
+    disabled?: boolean;
+};
+type __VLS_PublicProps = {
+    modelValue?: EmailRecipient[] | null;
+} & __VLS_Props;
+declare const _default: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:modelValue": (value: EmailRecipient[] | null) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:modelValue"?: ((value: EmailRecipient[] | null) => any) | undefined;
+}>, {
+    disabled: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/FindChatsDialog.d.ts

@@ -0,0 +1,12 @@
+type __VLS_Props = {
+    channel?: number | null;
+    token?: string;
+    /** Chats already on the list: shown ticked and not added twice. */
+    chosen?: string[];
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    channel: number | null;
+    token: string;
+    chosen: string[];
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/MessagePreview.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, HTMLElement>;
+export default _default;

package/dist/NewChannelDialog.d.ts

@@ -0,0 +1,6 @@
+import { NotificationsMeta } from './types';
+type __VLS_Props = {
+    meta: NotificationsMeta;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/NotificationsPage.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The section (§10.1): the channels, the log of what they sent, and the bin — three views of one
+ * list screen, the open one in the address (`?view=log`), so a link to the log is a link to it.
+ *
+ * A channel opens on a page of its own: its form is long, and the preview beside it needs the
+ * width a pane next to a list would take away.
+ */
+type __VLS_Props = {
+    base?: string;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    base: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

package/dist/TemplateField.d.ts

@@ -0,0 +1,25 @@
+import { LocalizedValue } from '@webx-ui/core';
+type __VLS_Props = {
+    localized?: boolean;
+    disabled?: boolean;
+    minHeight?: string;
+};
+type __VLS_PublicProps = {
+    modelValue?: string | LocalizedValue | null;
+} & __VLS_Props;
+declare const _default: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "update:modelValue": (value: string | LocalizedValue | null) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:modelValue"?: ((value: string | LocalizedValue | null) => any) | undefined;
+}>, {
+    disabled: boolean;
+    minHeight: string;
+    localized: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    editor: {
+        view: import('@codemirror/view').EditorView | null;
+        focus: () => void | undefined;
+        format: () => boolean;
+    } | null;
+}, HTMLDivElement>;
+export default _default;

package/dist/TestDialog.d.ts

@@ -0,0 +1,18 @@
+import { ScreenModel } from '@webx-ui/schema';
+type __VLS_Props = {
+    channel?: number | null;
+    values: ScreenModel;
+    /** The fixed recipients, as the server knows them by: a chat id, an address. */
+    recipients?: {
+        value: string;
+        label: string;
+    }[];
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    channel: number | null;
+    recipients: {
+        value: string;
+        label: string;
+    }[];
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/api.d.ts

@@ -0,0 +1,46 @@
+import { AdminContext } from '@webx-ui/module-admin';
+import { ScreenModel } from '@webx-ui/schema';
+import { Administrator, ChannelDetail, ChannelsList, CheckAnswer, DeliveriesPage, DeliveriesQuery, DeliveryRow, FoundChat, NotificationsMeta, ServerPreview, TestResult } from './types';
+export interface NotificationsApi {
+    /** The providers and the events the site has. */
+    meta(): Promise<NotificationsMeta>;
+    /** Every channel, the newest first; `event` narrows it (`none` — the ones for any event). */
+    channels(filter?: {
+        trashed?: boolean;
+        event?: string;
+    }): Promise<ChannelsList>;
+    get(id: number): Promise<ChannelDetail>;
+    /** A new channel out of the values of its form; a new channel of an event starts with its sample. */
+    create(values: ScreenModel): Promise<ChannelDetail>;
+    /**
+     * Only the fields given are written, so the switch in the list sends `{ enabled }` alone. An
+     * empty secret keeps the one saved; `forget` lists the ones to wipe.
+     */
+    save(id: number, values: ScreenModel): Promise<ChannelDetail>;
+    remove(id: number): Promise<void>;
+    restore(id: number): Promise<ChannelDetail>;
+    purge(id: number): Promise<void>;
+    /** A copy, switched off, its secrets carried over on the server. */
+    copy(id: number, name?: string): Promise<ChannelDetail>;
+    /** Sends now, past the queue, on the event's examples — through the form's values, not saved. */
+    test(id: number | null, values: ScreenModel, recipient?: string | null): Promise<TestResult[]>;
+    /** The server's render of the form's values: the check of the live preview. */
+    preview(id: number | null, values: ScreenModel, locale?: string): Promise<ServerPreview>;
+    /** The settings tried without sending: Telegram's getMe, an SMTP handshake. */
+    check(id: number | null, values: ScreenModel): Promise<CheckAnswer>;
+    /** The chats the bot has seen; with a token typed into the form or the saved one. */
+    findRecipients(input: {
+        provider: string;
+        channel?: number | null;
+        token?: string;
+    }): Promise<{
+        recipients: FoundChat[];
+        hint: string | null;
+    }>;
+    administrators(): Promise<Administrator[]>;
+    deliveries(query?: DeliveriesQuery): Promise<DeliveriesPage>;
+    retry(id: number): Promise<DeliveryRow>;
+}
+/** The path of the section under the panel's API. */
+export declare const NOTIFICATIONS_API = "notifications";
+export declare function createNotificationsApi(admin: AdminContext): NotificationsApi;

package/dist/context.d.ts

@@ -0,0 +1,21 @@
+import { ComputedRef, Ref } from 'vue';
+import { ScreenModel } from '@webx-ui/schema';
+import { NotificationEvent, NotificationProvider, NotificationsMeta } from './types';
+/**
+ * What the fields of a channel's form know about the form around them: the kind of channel and
+ * the event chosen in it, which decide what the template suggests and which addressees there
+ * are, and the record itself, which "Find chats" asks the saved token of.
+ *
+ * Provided by the channel's page; a field drawn anywhere else gets an empty one and works as a
+ * plain field — a template with only Mustache's syntax to suggest, chats without a search.
+ */
+export interface ChannelContext {
+    meta: Ref<NotificationsMeta | null>;
+    values: Ref<ScreenModel>;
+    /** The saved channel, or null for one not written yet. */
+    id: Ref<number | null>;
+    provider: ComputedRef<NotificationProvider | null>;
+    event: ComputedRef<NotificationEvent | null>;
+}
+export declare function provideChannel(meta: Ref<NotificationsMeta | null>, values: Ref<ScreenModel>, id: Ref<number | null>): ChannelContext;
+export declare function useChannel(): ChannelContext;

package/dist/i18n.d.ts

@@ -0,0 +1,2 @@
+/** Puts this package's English under the panel's dictionary, once per panel. */
+export declare function useNotificationsMessages(): void;

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { notifications, type NotificationsOptions } from './module';
+export { createNotificationsApi, NOTIFICATIONS_API, type NotificationsApi } from './api';
+export { notificationsMessages } from './messages';
+export { escapeFor, escapeHtml, examplesOf, renderMessage, renderTemplate, TemplateRefusal, type MessageInput, type RenderedMessage, type TemplateValues, } from './render';
+export { telegramHtml } from './telegram';
+export { addresseesOf, snippetOf, variablesOf } from './variables';
+export { provideChannel, useChannel, type ChannelContext } from './context';
+export { default as WxNotificationsPage } from './NotificationsPage';
+export { default as WxNotificationsChannelPage } from './ChannelPage';
+export { default as WxNotificationsPreview } from './MessagePreview';
+export { default as WxNotificationsTemplateField } from './TemplateField';
+export { default as WxNotificationsChatsField } from './ChatsField';
+export { default as WxNotificationsEmailsField } from './EmailsField';
+export { default as WxNotificationChannelsField } from './ChannelsField';
+export type * from './types';