@marinoscar/platform-web 0.1.0-next.3 → 0.1.0-next.4

package/dist/notifications/headless/types.d.ts

@@ -0,0 +1,424 @@
+/**
+ * A delivery channel id.
+ *
+ * OPEN: any id the API registered (an app's own included), with the three
+ * platform ids named for completion. The bundle holds no list of channels, no
+ * labels and no order: those come from `GET /api/notifications/channels`
+ * ({@link NotificationChannelDescriptor}), so an app's channel is drawn with no
+ * edit here. A stored preference or an event may name a channel this build has
+ * never heard of; rendering falls back to the raw id rather than a blank label.
+ *
+ * @stability experimental
+ */
+export type NotificationChannel = 'email' | 'browser' | 'push' | (string & {});
+/**
+ * One delivery channel, as served by `GET /api/notifications/channels`: field
+ * for field the API's `notificationChannelDescriptorSchema`. The only source of
+ * a channel's label, its place in a list, whether a critical broadcast may rely
+ * on it and whether a broadcast can be sent over it.
+ *
+ * @extensionPoint schema
+ * @stability experimental
+ */
+export interface NotificationChannelDescriptor {
+    /** The channel id; permanent. */
+    id: NotificationChannel;
+    /** The label to draw (`Email`, `Browser`, `Slack`). */
+    label: string;
+    /** One sentence on what the channel delivers to. */
+    description: string;
+    /** Whether a user may toggle the channel in their preferences. */
+    userConfigurable: boolean;
+    /** Whether a critical broadcast may rely on this channel (it leaves a durable record a recipient can read). */
+    criticalCapable: boolean;
+    /** Whether the broadcast events declare this channel, so a broadcast can be sent over it. */
+    broadcastCapable: boolean;
+    /** Whether a new broadcast starts with this channel selected. */
+    broadcastDefault: boolean;
+    /** Registration order, from 0: the order every list draws channels in. */
+    order: number;
+}
+/**
+ * One entry of the event registry, as served by `GET /api/notifications/events`.
+ *
+ * Field for field the API's `notificationEventSchema`. Note `mandatory` is a
+ * plain `boolean` here, not `boolean | undefined`: the API normalises it on the
+ * way out precisely so no client has to know that absent means "the user is in
+ * charge".
+  *
+  * @stability experimental
+ */
+export interface NotificationEventDef {
+    /** Stable key. What a preference is stored against; renaming one server-side is a migration. */
+    key: string;
+    /** Short human label — the row heading on the preferences page. */
+    label: string;
+    /** One sentence on what actually triggers this, in the user's terms. */
+    description: string;
+    /**
+     * Channels this event CAN be delivered over — a capability of the event, not
+     * a statement about which transports are implemented yet. A cell is rendered
+     * only for a channel listed here, so `allowlist.invitation` (email only, its
+     * recipient has no session by definition) never offers a browser toggle.
+     *
+     * NARROWED BY THE ADMIN POLICY: a non-mandatory event does not list
+     * `browser` while an administrator has browser notifications off or has
+     * suppressed that event. This is what the user will actually receive.
+     */
+    channels: NotificationChannel[];
+    /**
+     * The channels the event DECLARES in the registry, before administrator
+     * policy (#521). Only the admin notification-policy page should read this:
+     * it must keep listing an event whose browser delivery is suppressed, so the
+     * suppression can be undone. Everyone else reads `channels`.
+     */
+    declaredChannels: NotificationChannel[];
+    /** What an account that has expressed no preference receives. */
+    defaultEnabled: boolean;
+    /**
+     * The user may not opt out, on ANY channel.
+     *
+     * A UI HINT ONLY — the gate is server-side in preference resolution, because
+     * a client-side check is bypassed by any request that never went near the
+     * client. Render the controls disabled WITH the reason rather than hiding
+     * them: a dead toggle teaches nothing (epic #109, success criterion 5).
+     */
+    mandatory: boolean;
+}
+/**
+ * One channel's stored preferences: event key -\> the user's explicit choice.
+ *
+ * SPARSE. A key is present only where the user deliberately chose something. An
+ * absent key is NOT `false` and must never be normalised into one — absent
+ * means "use the registry's `defaultEnabled`", resolved at read time.
+  *
+  * @stability experimental
+ */
+export type NotificationChannelPreferences = Record<string, boolean>;
+/**
+ * The `notifications` namespace of the user-settings document, as stored.
+ *
+ * CHANNEL-OUTER, EVENT-INNER — `{ email: { 'user.welcome': false } }`. Not a
+ * choice this file makes: it is the shape the API's
+ * `readNotificationPreferences` parses and `isChannelEnabled` resolves, and a
+ * document written event-outer would be silently ignored by the dispatcher,
+ * i.e. a mute that never takes effect.
+ *
+ * Every level is optional, all the way down. There is deliberately no shape of
+ * this value that asserts "the user has an opinion about every event".
+  *
+  * @stability experimental
+ */
+export type NotificationPreferences = Partial<Record<NotificationChannel, NotificationChannelPreferences>>;
+/**
+ * PATCH form of one channel's preferences.
+ *
+ * The value is nullable because JSON Merge Patch uses `null` to mean DELETE:
+ * `{ email: { 'user.welcome': null } }` removes that one event key, restoring
+ * the absent (= registry default) state. That is what the preferences page
+ * sends when a control returns to its default — writing the default value
+ * explicitly works today and pins the user to today's default forever.
+  *
+  * @stability experimental
+ */
+export type NotificationChannelPreferencesPatch = Record<string, boolean | null>;
+/**
+ * PATCH form of the `notifications` namespace. Three levels of delete, each
+ * meaning something different (see `UserSettingsUpdate`).
+ *
+ * Unlike `dataTables`, a non-null channel object is DEEP-merged per event
+ * rather than replacing the channel wholesale — which is exactly what lets the
+ * page send one key per toggle and leave every other preference absent.
+  *
+  * @stability experimental
+ */
+export type NotificationPreferencesPatch = Partial<Record<NotificationChannel, NotificationChannelPreferencesPatch | null>>;
+/**
+ * One delivered notification, field for field the API's `notificationSchema`
+ * (`apps/api/src/notifications/dto/notification.dto.ts`).
+ *
+ * THE SAME SHAPE ARRIVES TWO WAYS — fetched from `GET /api/notifications`, or
+ * pushed over SSE — and that is deliberate on the API's side: a streamed event
+ * is this object minus `readAt`, so both go into the same list with no second
+ * mapping. See `streamEventToNotification` in `services/notificationStream.ts`,
+ * which is the only place the missing field is filled in.
+  *
+  * @stability experimental
+ */
+export interface AppNotification {
+    /** The row id. */
+    id: string;
+    /**
+     * The registry key that raised this (`security.role_changed`).
+     *
+     * For grouping, icons or filtering. NOT what is rendered — `title` and `body`
+     * were rendered server-side at write time, so editing a template never
+     * rewrites what a user was already told.
+     */
+    eventKey: string;
+    /** One short line. Already length-capped by the API. Render as TEXT. */
+    title: string;
+    /** The detail. Plain text, never markup. */
+    body: string;
+    /**
+     * Root-relative path to open, or `null`.
+     *
+     * GUARANTEED INTERNAL by the API — `sanitizeLink` validated it before the row
+     * was written, so it is always a single leading `/` with no scheme and no
+     * protocol-relative `//`. That is what makes it safe to hand to
+     * `navigate()`. The client still refuses anything that does not start with a
+     * single `/` (see `isInternalLink` in `NotificationBell.tsx`): the guarantee
+     * is the server's to keep, and a client that also checks costs one comparison
+     * and survives the day it is broken.
+     */
+    link: string | null;
+    /** ISO-8601. When the user marked it read; `null` while unread. */
+    readAt: string | null;
+    /** ISO-8601. */
+    createdAt: string;
+}
+/**
+ * A page of `GET /api/notifications`.
+ *
+ * FLAT pagination (`items`/`total`/`page`/`pageSize`/`totalPages`), matching
+ * `/users` and `/allowlist` rather than storage's nested `pagination` object —
+ * the API deliberately picked the more common of its two existing list shapes.
+  *
+  * @stability experimental
+ */
+export interface NotificationListResponse {
+    /** This page's rows, newest first. */
+    items: AppNotification[];
+    /** Matching rows in total. */
+    total: number;
+    /** The page number. */
+    page: number;
+    /** The page size. */
+    pageSize: number;
+    /** Pages in total. */
+    totalPages: number;
+}
+/**
+ * The badge number.
+ *
+ * Returned by `GET /api/notifications/unread-count` AND by BOTH mark-read
+ * endpoints — which is why marking one read costs a single round trip: the
+ * client already holds the row it marked, and the count is the only thing it
+ * cannot compute for itself. Do not follow a mark-read with a count fetch.
+  *
+  * @stability experimental
+ */
+export interface UnreadCountResponse {
+    /** Unread notifications. */
+    unreadCount: number;
+}
+/**
+ * One `event: notification` frame's payload, as `NotificationStreamService`
+ * publishes it.
+ *
+ * `AppNotification` WITHOUT `readAt`, PLUS `toast` — not an oversight and not a
+ * different model. `readAt` is absent because a notification is unread by
+ * definition at the instant it is published, so the field would carry no
+ * information. `toast` is present because it is an instruction about THIS
+ * delivery rather than a property of the stored row. Everything else is
+ * identical, which is the property that lets a streamed event be pushed
+ * straight into the fetched list.
+ *
+ * Carries NO user id. The recipient is implicit in which stream it arrived on;
+ * the API omits it specifically so no client is ever tempted to filter on it.
+  *
+  * @stability experimental
+ */
+export type NotificationStreamEvent = Omit<AppNotification, 'readAt'> & {
+    /**
+     * May this client raise an OS notification for this event? (#226, epic #215)
+     *
+     * SERVER-COMPUTED, from the administrator's deployment-wide policy:
+     * `browserEnabled && !disabledEvents.includes(eventKey)`. It travels with the
+     * event rather than being derived from a cached
+     * `GET /api/notifications/config`, so a tab open since before an
+     * administrator changed the setting still honours the current policy.
+     *
+     * `false` DOES NOT MEAN SUPPRESSED. The notification was recorded and this
+     * frame was sent; the bell, the unread count and the notification centre are
+     * unaffected. Only the OS bubble is withheld — which is what lets an
+     * administrator mute toasts without muting a mandatory security alert's
+     * durable record. Only a mandatory event arrives with `false`: a
+     * non-mandatory event the policy suppresses is not recorded or streamed.
+     *
+     * #227 is what acts on it. Until then it is parsed and carried, which is the
+     * harmless direction: a field ignored is cheaper than a field the client
+     * cannot see when it finally needs it.
+     */
+    toast: boolean;
+    /**
+     * Is this same notification ALSO being delivered to this user over Web Push?
+     * (#625) SERVER-COMPUTED at publish time: `true` when the event declares the
+     * push channel and the user has push subscriptions it will be sent to.
+     *
+     * Lets a tab with a live push subscription leave the OS bubble to the service
+     * worker instead of raising a second one of its own (see `handleNotification`
+     * in `contexts/NotificationContext.tsx`). It is a hint about delivery, never
+     * about the row, and it never affects the bell or the unread count.
+     *
+     * OPTIONAL, and a missing value means `false`: an older server does not send
+     * it, and "not pushed" is the safe reading — the page keeps its own toast.
+     */
+    pushed?: boolean;
+};
+/**
+ * `GET /api/notifications/config` — this deployment's client-facing
+ * notification capabilities (#226, epic #215). Field for field the API's
+ * `notificationConfigSchema` (`apps/api/src/notifications/dto/notification-config.dto.ts`),
+ * which carries the full argument for why this is its own narrow, unauthenticated-
+ * by-permission endpoint rather than a widening of `system_settings:read` — cited
+ * here rather than re-derived: a viewer holds no `system_settings:read`, so this
+ * is the one place that lets a non-admin learn the toggle without exposing the
+ * whole settings blob.
+  *
+  * @stability experimental
+ */
+export interface NotificationConfigResponse {
+    /**
+     * May this client raise browser notifications at all? THE PERMISSION-PROMPT
+     * GATE — see the DTO's own doc comment. `false` stops browser delivery of
+     * NON-MANDATORY events outright: no row is written, so they never reach the
+     * notification centre. MANDATORY events are still written and still reach
+     * the centre; only their OS bubble is withheld. Email is unaffected.
+     * Consumed by #227 as `useNotificationCapability`'s `adminDisabled` input
+     * (`!browserEnabled`).
+     */
+    browserEnabled: boolean;
+    /**
+     * May this client subscribe to Web Push? `true` once an administrator has
+     * generated and enabled a VAPID key pair (#355). Drives the boot-time
+     * subscription sync (`hooks/usePushSubscriptionSync.ts`, #365) and the
+     * settings page's push column.
+     */
+    pushEnabled: boolean;
+    /**
+     * The VAPID application server key (URL-safe base64) for
+     * `pushManager.subscribe`, or `null` when push is unavailable. Changes when
+     * the key pair is rotated, which is how the sync detects a stale
+     * subscription.
+     */
+    vapidPublicKey: string | null;
+}
+/**
+ * `POST /api/notifications/push/subscriptions` body — exactly the browser's
+ * `PushSubscription.toJSON()` shape, so the client passes it through unmodified
+ * (#229, wired by #365).
+  *
+  * @stability experimental
+ */
+export interface PushSubscriptionPayload {
+    /** The push service endpoint. */
+    endpoint: string;
+    /** When the browser says it expires (epoch ms), or null. */
+    expirationTime?: number | null;
+    /** The subscription's keys. */
+    keys: {
+        /** The client's P-256 public key. */
+        p256dh: string;
+        /** The client's auth secret. */
+        auth: string;
+    };
+}
+/**
+ * `POST /api/notifications/push/subscriptions` response.
+ *
+ * @stability experimental
+ */
+export interface PushSubscriptionResponse {
+    /** The subscription id. */
+    id: string;
+    /** The registered endpoint. */
+    endpoint: string;
+    /** Creation time (ISO 8601). */
+    createdAt: string;
+}
+/**
+ * The deployment-wide notification policy (`system_settings.notifications`,
+ * #225), as the admin Notifications page edits it. The organization layer
+ * (#738) has the same shape and can only tighten it.
+ *
+ * @stability experimental
+ */
+export interface SystemNotificationSettings {
+    /** The whole browser channel, for everyone. */
+    browserEnabled: boolean;
+    /**
+     * Event keys whose OS notification is suppressed for everyone. A plain
+     * `string[]`: a key this build has never heard of may still legitimately be
+     * suppressed, so the page leaves unknown stored keys alone.
+     */
+    disabledEvents: string[];
+    /**
+     * A switch per channel (`{ slack: { enabled: false } }`); an absent channel
+     * is enabled. `browser` is also `browserEnabled`, kept equal by the API.
+     * Absent on a deployment that never saved one.
+     */
+    channels?: Record<string, NotificationChannelSwitch>;
+}
+/**
+ * One channel's deployment-wide switch (an entry of
+ * {@link SystemNotificationSettings.channels}).
+ *
+ * @stability experimental
+ */
+export interface NotificationChannelSwitch {
+    /** Whether the channel delivers at all. */
+    enabled: boolean;
+}
+/**
+ * The least of the system settings document the admin Notifications page
+ * reads: the `notifications` block, the audit line and the row version. An
+ * app's own document type (with its other namespaces) is assignable to it.
+ *
+ * @stability experimental
+ */
+export interface NotificationsSystemSettingsDocument {
+    /** The notification policy. */
+    notifications: SystemNotificationSettings;
+    /** Last update (ISO 8601). */
+    updatedAt: string;
+    /** Who saved it last, or null. */
+    updatedBy: {
+        /** Their user id. */
+        id: string;
+        /** Their address. */
+        email: string;
+    } | null;
+    /** The row version, sent back as `If-Match`. */
+    version: number;
+}
+/**
+ * The least of the user settings document the user Notifications page reads:
+ * the stored preferences (absent until the user changes one) and the fields
+ * the settings hook needs.
+ *
+ * @stability experimental
+ */
+export interface NotificationsUserSettingsDocument {
+    /** The theme preference (unused by the page; the hook's document shape). */
+    theme: 'light' | 'dark' | 'system';
+    /** The profile preferences (unused by the page). */
+    profile: unknown;
+    /** The stored notification preferences; absent is the normal case. */
+    notifications?: NotificationPreferences;
+    /** Last update (ISO 8601). */
+    updatedAt: string;
+    /** The row version. */
+    version: number;
+}
+/**
+ * The `PATCH /user-settings` body the user Notifications page sends: the
+ * notification preferences, JSON Merge Patch (`null` deletes).
+ *
+ * @stability experimental
+ */
+export interface NotificationsUserSettingsUpdate {
+    /** The preferences patch, or null to clear the namespace. */
+    notifications?: NotificationPreferencesPatch | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/notifications/headless/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/notifications/headless/types.ts"],"names":[],"mappings":"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"}

package/dist/notifications/headless/types.js

@@ -0,0 +1,10 @@
+// =============================================================================
+// The notifications web wire types (issue #738; shapes from #121 to #355)
+// =============================================================================
+//
+// Moved from the reference app's `types/index.ts` with their meaning
+// unchanged, except that a channel id is OPEN (`NotificationChannel`). The
+// app re-exports them under the same names.
+// =============================================================================
+export {};
+//# sourceMappingURL=types.js.map

package/dist/notifications/headless/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/notifications/headless/types.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,0EAA0E;AAC1E,gFAAgF;AAChF,EAAE;AACF,qEAAqE;AACrE,2EAA2E;AAC3E,4CAA4C;AAC5C,gFAAgF"}

package/dist/notifications/headless/useBroadcasts.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The broadcast list and the writes (issue #325, epic #319; resume, #459).
+ *
+ * Two exports in one file, in the shape `hooks/useJobs.ts` establishes for an
+ * admin resource page: a list hook whose `refresh` does NOT raise the loading
+ * flag, and an actions hook with one in-flight flag and one error string. What
+ * they share is the contract — every function RESOLVES rather than throws, and
+ * a failure is a STRING the page renders — because every caller is a click
+ * handler that needs to branch, not a place to handle an exception that has
+ * already been captured for display.
+ *
+ * =============================================================================
+ * `useVisiblePolling` — RE-EXPORTED, NOT DEFINED HERE
+ * =============================================================================
+ *
+ * Same arrangement as `useJobs.ts` and `useWorkerNodes.ts`: there is exactly
+ * one implementation, in `hooks/useVisiblePolling.ts`, and it is re-exported
+ * from here so `BroadcastsPage` takes its polling from the hook module it
+ * already depends on — which is also what keeps a page test that mocks
+ * `hooks/useBroadcasts` in control of the poll.
+ *
+ * =============================================================================
+ * WHY THIS PAGE POLLS LESS EAGERLY THAN JOBS
+ * =============================================================================
+ *
+ * A queue is never at rest; a broadcast list usually is. Most of the time every
+ * row is `sent`, `canceled` or `failed` — states that cannot change with
+ * nobody touching them (a `failed` row only moves when an admin resumes it,
+ * which turns it `sending` and so re-enables the poll) — and polling those is a request per ten seconds
+ * for an answer that is known in advance. So `BroadcastsPage` passes `0` (which
+ * `useVisiblePolling` treats as "off") unless a row is actually `scheduled` or
+ * `sending`, and the interval below is what it passes when one is.
+ */
+import { useVisiblePolling } from './useVisiblePolling.js';
+import type { Broadcast, BroadcastCreateResult, BroadcastListParams, BroadcastTestResult, CreateBroadcastRequest } from './broadcasts.js';
+export { useVisiblePolling };
+/**
+ * How often the broadcasts page re-asks while something is in flight.
+ *
+ * The same ten seconds the jobs page uses, and for the same reason: the thing
+ * being watched is `recipientsDispatched` climbing through an audience in
+ * chunks, which a faster poll does not observe any better. Unlike Jobs, this
+ * interval is only ever REACHED while a row is `scheduled` or `sending` — see
+ * the file header.
+ */
+export declare const BROADCASTS_POLL_INTERVAL_MS = 10000;
+export interface UseBroadcastsResult {
+    broadcasts: Broadcast[];
+    total: number;
+    isLoading: boolean;
+    error: string | null;
+    /** Run a query, and remember it so `refresh` can repeat it. */
+    fetchBroadcasts: (params?: BroadcastListParams) => Promise<void>;
+    /** Re-run the last query. What the poll calls, and what a write calls after it lands. */
+    refresh: () => Promise<void>;
+}
+export declare function useBroadcasts(): UseBroadcastsResult;
+export interface UseBroadcastActionsResult {
+    /** True while any one of the writes is in flight. */
+    isWorking: boolean;
+    /** The last failure, or `null`. Cleared when a write starts. */
+    error: string | null;
+    clearError: () => void;
+    /** The created row plus its non-fatal warnings, or `null` when it failed. */
+    create: (body: CreateBroadcastRequest) => Promise<BroadcastCreateResult | null>;
+    /** `true` when the write landed. Never throws. */
+    cancel: (id: string) => Promise<boolean>;
+    /** Continue a `failed` broadcast from where it stopped. `true` when it landed. */
+    resume: (id: string) => Promise<boolean>;
+    remove: (id: string) => Promise<boolean>;
+    /** What was dispatched to the caller themselves, or `null` when it failed. */
+    sendTest: (body: CreateBroadcastRequest) => Promise<BroadcastTestResult | null>;
+}
+/**
+ * The writes, sharing one in-flight flag and one error.
+ *
+ * ONE FLAG FOR ALL OF THEM, as `useJobActions` does: they all mutate the same
+ * list, the page re-reads it after any of them, and a second write started
+ * while the first is landing would report its result over the top of the
+ * first's. Disabling the whole action set for the duration is the honest
+ * reading of "these are not independent".
+ *
+ * `sendTest` is in this set even though it mutates NOTHING — it stores no row
+ * and queues no job. It shares the flag anyway because it shares the composer:
+ * a test send and a real send are the same form, and letting the admin submit
+ * for real while a test of the same composition is in flight is how you get two
+ * conflicting snackbars over one dialog.
+ */
+export declare function useBroadcastActions(onChanged?: () => void): UseBroadcastActionsResult;
+//# sourceMappingURL=useBroadcasts.d.ts.map

package/dist/notifications/headless/useBroadcasts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBroadcasts.d.ts","sourceRoot":"","sources":["../../../src/notifications/headless/useBroadcasts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAIH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAS3D,OAAO,KAAK,EACV,SAAS,EACT,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAE7B;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAsBlD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,+DAA+D;IAC/D,eAAe,EAAE,CAAC,MAAM,CAAC,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,yFAAyF;IACzF,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,wBAAgB,aAAa,IAAI,mBAAmB,CA4DnD;AAMD,MAAM,WAAW,yBAAyB;IACxC,qDAAqD;IACrD,SAAS,EAAE,OAAO,CAAC;IACnB,gEAAgE;IAChE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,6EAA6E;IAC7E,MAAM,EAAE,CAAC,IAAI,EAAE,sBAAsB,KAAK,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;IAChF,kDAAkD;IAClD,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,kFAAkF;IAClF,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,8EAA8E;IAC9E,QAAQ,EAAE,CAAC,IAAI,EAAE,sBAAsB,KAAK,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAC;CACjF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,CAAC,EAAE,MAAM,IAAI,GAAG,yBAAyB,CAkFrF"}