@flowdular/sdk 0.2.4 → 0.3.1

package/modules/notifications/src/client/api.ts

@@ -0,0 +1,382 @@
+import { t } from '@flowdular/sdk/client/i18n';
+import type {
+	CreateWebhookSubscriptionInput,
+	DeliveryAttempt,
+	DeliveryStatus,
+	InboxTransition,
+	InboxTransitionOutcome,
+	NotificationKind,
+	MemberNotificationSettings,
+	NotificationPreference,
+	NotificationsInbox,
+	NotificationsInboxStatus,
+	WebhookSubscription,
+	WebhookSubscriptionSecret,
+} from '../domain/types.ts';
+
+interface ErrorEnvelope {
+	readonly error?: {
+		readonly code?: string;
+		readonly message?: string;
+	};
+}
+
+/** A failed request with the server's stable code, so a screen can translate it. */
+export class NotificationsApiError extends Error {
+	readonly status: number;
+	readonly code: string;
+
+	constructor(status: number, code: string, message: string) {
+		super(message);
+		this.name = 'NotificationsApiError';
+		this.status = status;
+		this.code = code;
+	}
+}
+
+/**
+ * The server message is English and written for an operator. A code this module
+ * knows becomes translated copy; anything else keeps the server's own sentence
+ * rather than hiding what went wrong behind a generic line.
+ */
+export function notificationsErrorMessage(
+	error: unknown,
+	fallbackKey: string,
+): string {
+	if (error instanceof NotificationsApiError) {
+		const key = 'notifications.error.code.' + error.code;
+		const translated = t(key);
+		if (translated !== key) return translated;
+		return error.message;
+	}
+	if (error instanceof Error && error.message !== '') return error.message;
+	return t(fallbackKey);
+}
+
+async function payload<T>(response: Response): Promise<T> {
+	const value = (await response.json()) as T & ErrorEnvelope;
+	if (!response.ok) {
+		throw new NotificationsApiError(
+			response.status,
+			value.error?.code ?? 'REQUEST_FAILED',
+			value.error?.message ?? t('notifications.error.request'),
+		);
+	}
+	return value;
+}
+
+async function get<T>(path: string): Promise<T> {
+	return payload<T>(
+		await fetch(path, {
+			headers: { accept: 'application/json' },
+			credentials: 'same-origin',
+		}),
+	);
+}
+
+async function post<T>(
+	path: string,
+	body: unknown,
+	csrfToken: string,
+): Promise<T> {
+	return payload<T>(
+		await fetch(path, {
+			method: 'POST',
+			headers: {
+				'content-type': 'application/json',
+				'x-csrf-token': csrfToken,
+			},
+			credentials: 'same-origin',
+			body: JSON.stringify(body),
+		}),
+	);
+}
+
+function query(entries: Readonly<Record<string, string>>): string {
+	const parameters = new URLSearchParams();
+	for (const [key, value] of Object.entries(entries)) {
+		if (value !== '') parameters.set(key, value);
+	}
+	const text = parameters.toString();
+	return text === '' ? '' : '?' + text;
+}
+
+/** One page of a list the server sorted, narrowed and cut. */
+export interface ListPage<Item> {
+	readonly items: readonly Item[];
+	readonly page: {
+		/** Null on the last page. */
+		readonly nextCursor: string | null;
+		readonly limit: number;
+	};
+}
+
+/** The most rows one list request may ask for; the server refuses more. */
+export const LIST_PAGE_MAX = 200;
+
+/** What every list request carries besides its own filters. */
+export interface PageRequest {
+	readonly limit?: number;
+	readonly direction?: 'asc' | 'desc';
+	/** The opaque cursor of the page, none for the first. */
+	readonly cursor?: string;
+}
+
+function pageQuery(request: PageRequest): Readonly<Record<string, string>> {
+	return {
+		limit: request.limit === undefined ? '' : String(request.limit),
+		direction: request.direction ?? '',
+		cursor: request.cursor ?? '',
+	};
+}
+
+export interface InboxFilter extends PageRequest {
+	readonly status?: NotificationsInboxStatus | '';
+	readonly kind?: NotificationKind | '';
+}
+
+export async function loadInbox(
+	filter: InboxFilter = {},
+): Promise<ListPage<NotificationsInbox>> {
+	return get<ListPage<NotificationsInbox>>(
+		'/api/notifications/inbox' +
+			query({
+				status: filter.status ?? '',
+				kind: filter.kind ?? '',
+				...pageQuery(filter),
+			}),
+	);
+}
+
+export async function loadUnreadCount(): Promise<number> {
+	return (
+		await get<{ readonly unread: number }>(
+			'/api/notifications/inbox/unread-count',
+		)
+	).unread;
+}
+
+async function inboxTransition(
+	path: string,
+	id: string,
+	csrfToken: string,
+): Promise<NotificationsInbox> {
+	return (
+		await post<{ readonly item: NotificationsInbox }>(path, { id }, csrfToken)
+	).item;
+}
+
+export async function markInboxRead(
+	id: string,
+	csrfToken: string,
+): Promise<NotificationsInbox> {
+	return inboxTransition('/api/notifications/inbox/mark-read', id, csrfToken);
+}
+
+export async function markInboxUnread(
+	id: string,
+	csrfToken: string,
+): Promise<NotificationsInbox> {
+	return inboxTransition('/api/notifications/inbox/mark-unread', id, csrfToken);
+}
+
+export async function archiveInboxItem(
+	id: string,
+	csrfToken: string,
+): Promise<NotificationsInbox> {
+	return inboxTransition('/api/notifications/inbox/archive', id, csrfToken);
+}
+
+/** One transition over many items; the server answers one outcome per id. */
+export async function transitionInboxItems(
+	ids: readonly string[],
+	transition: InboxTransition,
+	csrfToken: string,
+): Promise<readonly InboxTransitionOutcome[]> {
+	return (
+		await post<{ readonly outcomes: readonly InboxTransitionOutcome[] }>(
+			'/api/notifications/inbox/transition-many',
+			{ ids, transition },
+			csrfToken,
+		)
+	).outcomes;
+}
+
+export interface NotificationPreferences {
+	readonly kinds: readonly NotificationKind[];
+	readonly preferences: readonly NotificationPreference[];
+	/** The member's workspace-wide switches, defaults included. */
+	readonly member: MemberNotificationSettings;
+}
+
+export async function loadPreferences(): Promise<NotificationPreferences> {
+	return get<NotificationPreferences>('/api/notifications/preferences');
+}
+
+export async function savePreference(
+	kind: NotificationKind,
+	enabled: boolean,
+	csrfToken: string,
+): Promise<NotificationPreference> {
+	return (
+		await post<{ readonly preference: NotificationPreference }>(
+			'/api/notifications/preferences/save',
+			{ kind, enabled },
+			csrfToken,
+		)
+	).preference;
+}
+
+export async function saveEmailDelivery(
+	enabled: boolean,
+	csrfToken: string,
+): Promise<MemberNotificationSettings> {
+	return (
+		await post<{ readonly member: MemberNotificationSettings }>(
+			'/api/notifications/preferences/email',
+			{ enabled },
+			csrfToken,
+		)
+	).member;
+}
+
+export interface WebhookFilter extends PageRequest {
+	readonly status?: WebhookSubscription['status'] | '';
+	/** A substring of the name or the URL. */
+	readonly search?: string;
+}
+
+export async function loadWebhooks(
+	filter: WebhookFilter = {},
+): Promise<ListPage<WebhookSubscription>> {
+	return get<ListPage<WebhookSubscription>>(
+		'/api/notifications/webhooks' +
+			query({
+				status: filter.status ?? '',
+				q: filter.search ?? '',
+				...pageQuery(filter),
+			}),
+	);
+}
+
+/** The response that carries the secret; it is never readable again. */
+export async function createWebhook(
+	input: CreateWebhookSubscriptionInput,
+	csrfToken: string,
+): Promise<WebhookSubscriptionSecret> {
+	return post<WebhookSubscriptionSecret>(
+		'/api/notifications/webhooks',
+		input,
+		csrfToken,
+	);
+}
+
+export async function updateWebhook(
+	id: string,
+	input: CreateWebhookSubscriptionInput,
+	csrfToken: string,
+): Promise<WebhookSubscription> {
+	return (
+		await post<{ readonly subscription: WebhookSubscription }>(
+			'/api/notifications/webhooks/update',
+			{ id, ...input },
+			csrfToken,
+		)
+	).subscription;
+}
+
+async function webhookTransition(
+	path: string,
+	id: string,
+	csrfToken: string,
+): Promise<WebhookSubscription> {
+	return (
+		await post<{ readonly subscription: WebhookSubscription }>(
+			path,
+			{ id },
+			csrfToken,
+		)
+	).subscription;
+}
+
+export async function pauseWebhook(
+	id: string,
+	csrfToken: string,
+): Promise<WebhookSubscription> {
+	return webhookTransition('/api/notifications/webhooks/pause', id, csrfToken);
+}
+
+export async function resumeWebhook(
+	id: string,
+	csrfToken: string,
+): Promise<WebhookSubscription> {
+	return webhookTransition('/api/notifications/webhooks/resume', id, csrfToken);
+}
+
+export async function disableWebhook(
+	id: string,
+	csrfToken: string,
+): Promise<WebhookSubscription> {
+	return webhookTransition(
+		'/api/notifications/webhooks/disable',
+		id,
+		csrfToken,
+	);
+}
+
+/** The second and last response that carries a secret. */
+export async function rotateWebhookSecret(
+	id: string,
+	csrfToken: string,
+): Promise<WebhookSubscriptionSecret> {
+	return post<WebhookSubscriptionSecret>(
+		'/api/notifications/webhooks/rotate-secret',
+		{ id },
+		csrfToken,
+	);
+}
+
+export async function deleteWebhook(
+	id: string,
+	csrfToken: string,
+): Promise<void> {
+	await post<{ readonly deleted: string }>(
+		'/api/notifications/webhooks/delete',
+		{ id },
+		csrfToken,
+	);
+}
+
+export interface DeliveryFilter extends PageRequest {
+	readonly status?: DeliveryStatus | '';
+	readonly subscriptionId?: string;
+	/** A substring of the source reference or the source module. */
+	readonly search?: string;
+}
+
+export async function loadDeliveries(
+	filter: DeliveryFilter = {},
+): Promise<ListPage<DeliveryAttempt>> {
+	return get<ListPage<DeliveryAttempt>>(
+		'/api/notifications/deliveries' +
+			query({
+				status: filter.status ?? '',
+				subscription: filter.subscriptionId ?? '',
+				q: filter.search ?? '',
+				...pageQuery(filter),
+			}),
+	);
+}
+
+export async function replayDelivery(
+	id: string,
+	csrfToken: string,
+): Promise<DeliveryAttempt> {
+	return (
+		await post<{ readonly delivery: DeliveryAttempt }>(
+			'/api/notifications/deliveries/replay',
+			{ id },
+			csrfToken,
+		)
+	).delivery;
+}

package/modules/notifications/src/client/contribution.tsrx

@@ -0,0 +1,83 @@
+import { type ModuleClientContribution } from '@flowdular/sdk/client';
+import translationsEn from '../../translations/en.json';
+import translationsPl from '../../translations/pl.json';
+import { NOTIFICATIONS_PERMISSIONS } from '../acl/permissions.ts';
+import { DeliveriesView } from './DeliveriesView.tsrx';
+import {
+	NOTIFICATIONS_UNREAD_WIDGET,
+	NOTIFICATIONS_VIEWS,
+	notificationsAccountMenu,
+	notificationsNavigation,
+} from './navigation.ts';
+import {
+	NotificationPreferencesView,
+} from './NotificationPreferencesView.tsrx';
+import { NotificationsInboxView } from './NotificationsInboxView.tsrx';
+import { UnreadCountWidget } from './UnreadCountWidget.tsrx';
+import { WebhooksView } from './WebhooksView.tsrx';
+import './notifications.css';
+
+export interface NotificationsClientContributionOptions {
+	readonly csrfToken: string;
+	readonly scopes: readonly string[];
+}
+
+export function createNotificationsClientContribution(
+	options: NotificationsClientContributionOptions,
+): ModuleClientContribution {
+	const canManageInbox = options.scopes.includes(
+		NOTIFICATIONS_PERMISSIONS.manage,
+	);
+	const canManageWebhooks = options.scopes.includes(
+		NOTIFICATIONS_PERMISSIONS.webhooksManage,
+	);
+	const canReadWebhooks = options.scopes.includes(
+		NOTIFICATIONS_PERMISSIONS.webhooksRead,
+	);
+	return {
+		moduleId: 'notifications.core',
+		translations: { en: translationsEn, pl: translationsPl },
+		navigation: notificationsNavigation,
+		accountMenu: notificationsAccountMenu,
+		views: [
+			{
+				id: NOTIFICATIONS_VIEWS.inbox,
+				render: () =>
+					<NotificationsInboxView
+						csrfToken={options.csrfToken}
+						canManage={canManageInbox}
+					/>,
+			},
+			{
+				id: NOTIFICATIONS_VIEWS.preferences,
+				render: () =>
+					<NotificationPreferencesView
+						csrfToken={options.csrfToken}
+						canManage={canManageInbox}
+					/>,
+			},
+			{
+				id: NOTIFICATIONS_VIEWS.webhooks,
+				render: () =>
+					<WebhooksView
+						csrfToken={options.csrfToken}
+						canManage={canManageWebhooks}
+					/>,
+			},
+			{
+				id: NOTIFICATIONS_VIEWS.deliveries,
+				render: () =>
+					<DeliveriesView
+						csrfToken={options.csrfToken}
+						canReadWebhooks={canReadWebhooks}
+					/>,
+			},
+		],
+		widgets: [
+			{
+				...NOTIFICATIONS_UNREAD_WIDGET,
+				render: () => <UnreadCountWidget />,
+			},
+		],
+	};
+}

package/modules/notifications/src/client/inbox.ts

@@ -0,0 +1,41 @@
+import type {
+	NotificationKind,
+	NotificationsInbox,
+	NotificationsInboxStatus,
+} from '../domain/types.ts';
+
+/**
+ * Filters the reader chose. The default inbox is everything the member has not
+ * archived, which the server applies on its own; it is not one of them.
+ */
+export function inboxActiveFilters(
+	statusFilter: NotificationsInboxStatus | '',
+	kindFilter: NotificationKind | '',
+): number {
+	return (statusFilter === '' ? 0 : 1) + (kindFilter === '' ? 0 : 1);
+}
+
+export type InboxRowAction = 'open' | 'archive' | 'mark-unread';
+
+/* Opening the record is the one action every member has, and the only way to
+   reach it from the keyboard, since the row itself is not a control. A manager
+   also gets the one change that moves the item out of the list being read;
+   read and unread stay in the drawer, because a third button no longer fits
+   the row in every locale. */
+export function inboxRowActions(
+	status: NotificationsInboxStatus,
+	canManage: boolean,
+): readonly InboxRowAction[] {
+	if (!canManage) return ['open'];
+	return ['open', status === 'archived' ? 'mark-unread' : 'archive'];
+}
+
+/** The drawer reads its record from everything loaded, so a row that leaves the
+ * narrowed set through the change the reader just made keeps the drawer open. */
+export function selectedInboxItem(
+	items: readonly NotificationsInbox[],
+	selectedId: string | null,
+): NotificationsInbox | null {
+	if (selectedId === null) return null;
+	return items.find((item) => item.id === selectedId) ?? null;
+}

package/modules/notifications/src/client/index.ts

@@ -0,0 +1,29 @@
+import type {
+	ModuleClientContext,
+	ModuleClientContribution,
+} from '@flowdular/sdk/client';
+import { createNotificationsClientContribution as canonicalContribution } from './contribution.tsrx';
+
+export { createNotificationsClientContribution } from './contribution.tsrx';
+export type { NotificationsClientContributionOptions } from './contribution.tsrx';
+export { DeliveriesView } from './DeliveriesView.tsrx';
+export { NotificationPreferencesView } from './NotificationPreferencesView.tsrx';
+export { NotificationsInboxView } from './NotificationsInboxView.tsrx';
+export { UnreadCountWidget } from './UnreadCountWidget.tsrx';
+export { WebhooksView } from './WebhooksView.tsrx';
+export {
+	NOTIFICATIONS_UNREAD_WIDGET,
+	NOTIFICATIONS_VIEWS,
+	notificationsAccountMenu,
+	notificationsNavigation,
+} from './navigation.ts';
+
+/* Canonical entry used by the generated platform composition. */
+export function createClientContribution(
+	context: ModuleClientContext,
+): ModuleClientContribution {
+	return canonicalContribution({
+		csrfToken: context.csrfToken,
+		scopes: context.scopes,
+	});
+}

package/modules/notifications/src/client/navigation.ts

@@ -0,0 +1,92 @@
+import type {
+	AccountMenuContribution,
+	NavigationContribution,
+	WorkspaceSlot,
+} from '@flowdular/sdk/client';
+import { t } from '@flowdular/sdk/client/i18n';
+import { NOTIFICATIONS_PERMISSIONS } from '../acl/permissions.ts';
+
+/** The view ids the contribution registers and every entry points at. */
+export const NOTIFICATIONS_VIEWS = {
+	inbox: 'notifications-inbox',
+	preferences: 'notifications-preferences',
+	webhooks: 'notifications-webhooks',
+	deliveries: 'notifications-deliveries',
+} as const;
+
+/* Labels are read every render so a locale change reaches an entry the shell
+   built once. */
+export const notificationsNavigation: readonly NavigationContribution[] = [
+	{
+		id: 'notifications.navigation.inbox',
+		viewId: NOTIFICATIONS_VIEWS.inbox,
+		group: 'Workspace',
+		get label() {
+			return t('notifications.navigation.inbox');
+		},
+		glyph: 'activity',
+		get description() {
+			return t('notifications.navigation.inboxDescription');
+		},
+		scope: NOTIFICATIONS_PERMISSIONS.read,
+		order: 20,
+	},
+	{
+		id: 'notifications.navigation.webhooks',
+		viewId: NOTIFICATIONS_VIEWS.webhooks,
+		group: 'Administration',
+		get label() {
+			return t('notifications.navigation.webhooks');
+		},
+		glyph: 'plug',
+		get description() {
+			return t('notifications.navigation.webhooksDescription');
+		},
+		scope: NOTIFICATIONS_PERMISSIONS.webhooksRead,
+		order: 60,
+	},
+	{
+		id: 'notifications.navigation.deliveries',
+		viewId: NOTIFICATIONS_VIEWS.deliveries,
+		group: 'Administration',
+		get label() {
+			return t('notifications.navigation.deliveries');
+		},
+		glyph: 'activity',
+		get description() {
+			return t('notifications.navigation.deliveriesDescription');
+		},
+		scope: NOTIFICATIONS_PERMISSIONS.deliveriesRead,
+		order: 61,
+	},
+];
+
+/* Preferences belong to the person, not to the workspace, so they are reached
+   from the account menu like the profile screen. */
+export const notificationsAccountMenu: readonly AccountMenuContribution[] = [
+	{
+		id: 'notifications.account-menu.preferences',
+		viewId: NOTIFICATIONS_VIEWS.preferences,
+		get label() {
+			return t('notifications.navigation.preferences');
+		},
+		get description() {
+			return t('notifications.navigation.preferencesDescription');
+		},
+		glyph: 'settings',
+		scope: NOTIFICATIONS_PERMISSIONS.read,
+		order: 20,
+	},
+];
+
+export const NOTIFICATIONS_UNREAD_WIDGET: {
+	readonly id: string;
+	readonly slot: WorkspaceSlot;
+	readonly scope: string;
+	readonly order: number;
+} = {
+	id: 'notifications.topbar.unread',
+	slot: 'topbar.actions',
+	scope: NOTIFICATIONS_PERMISSIONS.read,
+	order: 10,
+};

package/modules/notifications/src/client/notifications.css

@@ -0,0 +1,70 @@
+/* Notifications module: composites specific to this module. Primitives (buttons,
+   fields, tags, cards) come from @flowdular/sdk/ui and are not restyled here. */
+
+.notifications-unread {
+	display: inline-flex;
+	height: 34px;
+	align-items: center;
+	gap: 6px;
+	padding: 0 10px;
+	color: var(--ink-2);
+	text-decoration: none;
+	background: var(--surface);
+	border: 1px solid var(--line);
+	border-radius: var(--r);
+}
+
+.notifications-unread:hover {
+	color: var(--primary);
+	border-color: var(--primary);
+}
+
+.notifications-unread__count {
+	min-width: 18px;
+	padding: 0 5px;
+	font-size: var(--text-xs);
+	font-weight: 600;
+	line-height: 18px;
+	color: var(--primary);
+	text-align: center;
+	background: var(--primary-tint);
+	border-radius: 999px;
+}
+
+/* A ledger reference is one token with nowhere to break, so it would push the
+   row sideways. The cell keeps its budget and the full value stays readable in
+   the title. */
+.notifications-truncate {
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+.notifications-facts {
+	display: grid;
+	grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
+	gap: 10px 16px;
+	margin: 0;
+}
+
+.notifications-facts__item {
+	display: grid;
+	min-width: 0;
+	gap: 4px;
+}
+
+.notifications-facts dd {
+	min-width: 0;
+	margin: 0;
+	font-size: var(--text-md);
+	overflow-wrap: anywhere;
+}
+
+.notifications-body {
+	margin: 0;
+	font-size: var(--text-md);
+	line-height: 1.55;
+	color: var(--ink-2);
+	white-space: pre-wrap;
+	overflow-wrap: anywhere;
+}