@burdenoff/fe-libs 2026.1112.6 → 2026.1113.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/dist/shared/assistant/i18nManifest.d.ts +40 -0
  2. package/dist/shared/assistant/i18nManifest.js +40 -0
  3. package/dist/shared/proactive/ProactiveProvider.d.ts +67 -0
  4. package/dist/shared/proactive/ProactiveProvider.js +128 -0
  5. package/dist/shared/proactive/actions.d.ts +101 -0
  6. package/dist/shared/proactive/actions.js +71 -0
  7. package/dist/shared/proactive/activity.d.ts +27 -0
  8. package/dist/shared/proactive/activity.js +37 -0
  9. package/dist/shared/proactive/adapters.d.ts +54 -0
  10. package/dist/shared/proactive/adapters.js +62 -0
  11. package/dist/shared/proactive/anchors.d.ts +47 -0
  12. package/dist/shared/proactive/anchors.js +53 -0
  13. package/dist/shared/proactive/budget.d.ts +17 -0
  14. package/dist/shared/proactive/budget.js +30 -0
  15. package/dist/shared/proactive/capabilities.d.ts +26 -0
  16. package/dist/shared/proactive/capabilities.js +63 -0
  17. package/dist/shared/proactive/coalesce.d.ts +11 -0
  18. package/dist/shared/proactive/coalesce.js +15 -0
  19. package/dist/shared/proactive/context.d.ts +42 -0
  20. package/dist/shared/proactive/context.js +31 -0
  21. package/dist/shared/proactive/flags.d.ts +5 -0
  22. package/dist/shared/proactive/flags.js +11 -0
  23. package/dist/shared/proactive/index.d.ts +40 -0
  24. package/dist/shared/proactive/metadata.d.ts +48 -0
  25. package/dist/shared/proactive/metadata.js +126 -0
  26. package/dist/shared/proactive/operations.d.ts +96 -0
  27. package/dist/shared/proactive/operations.js +117 -0
  28. package/dist/shared/proactive/severityCopy.d.ts +4 -0
  29. package/dist/shared/proactive/severityCopy.js +10 -0
  30. package/dist/shared/proactive/snooze.d.ts +4 -0
  31. package/dist/shared/proactive/snooze.js +9 -0
  32. package/dist/shared/proactive/transport.d.ts +32 -0
  33. package/dist/shared/proactive/transport.js +124 -0
  34. package/dist/shared/proactive/types.d.ts +83 -0
  35. package/dist/shared/proactive/ui/ProactiveInbox.d.ts +20 -0
  36. package/dist/shared/proactive/ui/ProactiveInbox.js +78 -0
  37. package/dist/shared/proactive/ui/ProactiveSettingsPanel.d.ts +8 -0
  38. package/dist/shared/proactive/ui/ProactiveSettingsPanel.js +210 -0
  39. package/dist/shared/proactive/ui/SuggestionAnchorsLayer.d.ts +9 -0
  40. package/dist/shared/proactive/ui/SuggestionAnchorsLayer.js +140 -0
  41. package/dist/shared/proactive/ui/SuggestionBadge.d.ts +11 -0
  42. package/dist/shared/proactive/ui/SuggestionBadge.js +53 -0
  43. package/dist/shared/proactive/ui/SuggestionCard.d.ts +23 -0
  44. package/dist/shared/proactive/ui/SuggestionCard.js +119 -0
  45. package/dist/shared/proactive/ui/anchorLayerDom.d.ts +28 -0
  46. package/dist/shared/proactive/ui/anchorLayerDom.js +23 -0
  47. package/dist/shared/proactive/useProactiveSession.d.ts +56 -0
  48. package/dist/shared/proactive/useProactiveSession.js +150 -0
  49. package/dist/shared/proactive/useSuggestionControls.d.ts +25 -0
  50. package/dist/shared/proactive/useSuggestionControls.js +118 -0
  51. package/dist/shared/providers/shell/PermissionProvider.d.ts +16 -0
  52. package/dist/shared/providers/shell/PermissionProvider.js +51 -30
  53. package/dist/shared/providers/shell/index.d.ts +1 -1
  54. package/dist/shared-proactive.d.ts +2 -0
  55. package/dist/shared-proactive.js +21 -0
  56. package/dist/shared-providers-shell.js +14 -14
  57. package/package.json +5 -1
@@ -588,6 +588,46 @@ export declare const ASSISTANT_I18N_LITERAL_COPY: {
588
588
  readonly 'preview.close': "Close preview";
589
589
  readonly 'preview.failed': "The preview could not be displayed.";
590
590
  readonly 'preview.title': "Preview";
591
+ readonly 'proactive.assistantPrompt': "Help me with this AI suggestion about {{entityType}} {{entityId}}: \"{{title}}\". {{why}}";
592
+ readonly 'proactive.card.actionFailed': "That didn't work. Try again, or open it yourself.";
593
+ readonly 'proactive.card.actionUnavailable': "This action isn't available any more.";
594
+ readonly 'proactive.card.aiBadge': "AI suggestion";
595
+ readonly 'proactive.card.dismiss': "Dismiss";
596
+ readonly 'proactive.card.dismissFailed': "Couldn't dismiss this suggestion. Try again.";
597
+ readonly 'proactive.card.snoozeDay': "Snooze 1 day";
598
+ readonly 'proactive.card.snoozeFailed': "Couldn't snooze this suggestion. Try again.";
599
+ readonly 'proactive.card.snoozeWeek': "Snooze 1 week";
600
+ readonly 'proactive.count.many': "{{count}} AI suggestions";
601
+ readonly 'proactive.count.none': "No AI suggestions";
602
+ readonly 'proactive.count.one': "1 AI suggestion";
603
+ readonly 'proactive.inbox.button': "Suggestions";
604
+ readonly 'proactive.inbox.buttonWithCount': "Suggestions ({{count}})";
605
+ readonly 'proactive.inbox.empty': "No suggestions right now. When the assistant finds something worth a look, it shows up here.";
606
+ readonly 'proactive.inbox.title': "Suggestions";
607
+ readonly 'proactive.pin.cardLabel': "AI suggestion";
608
+ readonly 'proactive.pin.label': "AI suggestion: {{title}}";
609
+ readonly 'proactive.settings.consent': "When this is on, the assistant looks through {{product}} in the background to find problems and opportunities. It reads as you and only reads: it never changes anything, and every suggestion waits for you to act on it.";
610
+ readonly 'proactive.settings.consentUntil': "Your permission lasts until {{date}}. Turning this off withdraws it at once.";
611
+ readonly 'proactive.settings.frequency.daily': "In a daily digest";
612
+ readonly 'proactive.settings.frequency.immediate': "As they come";
613
+ readonly 'proactive.settings.frequency.weekly': "In a weekly digest";
614
+ readonly 'proactive.settings.frequencyLegend': "When you're away, send suggestions";
615
+ readonly 'proactive.settings.frequencyUnavailable': "Saved. The delivery choice can't be stored yet, so suggestions arrive as they come.";
616
+ readonly 'proactive.settings.loadFailed': "Your suggestion settings couldn't be loaded.";
617
+ readonly 'proactive.settings.loading': "Loading your suggestion settings…";
618
+ readonly 'proactive.settings.productFallback': "this app";
619
+ readonly 'proactive.settings.quietHours': "Quiet hours and delivery channels";
620
+ readonly 'proactive.settings.retry': "Try again";
621
+ readonly 'proactive.settings.save': "Save";
622
+ readonly 'proactive.settings.saveFailed': "Your settings couldn't be saved. Try again.";
623
+ readonly 'proactive.settings.saved': "Saved.";
624
+ readonly 'proactive.settings.saving': "Saving…";
625
+ readonly 'proactive.settings.title': "Proactive suggestions";
626
+ readonly 'proactive.settings.toggle': "Let the assistant look for suggestions";
627
+ readonly 'proactive.severity.high': "High";
628
+ readonly 'proactive.severity.low': "Low";
629
+ readonly 'proactive.severity.medium': "Medium";
630
+ readonly 'proactive.severity.urgent': "Urgent";
591
631
  readonly 'sheet.collapse': "Shrink the assistant";
592
632
  readonly 'sheet.expand': "Expand the assistant";
593
633
  readonly 'speech.codeBlock': "Code block";
@@ -481,6 +481,46 @@ var g = {
481
481
  "preview.close": "Close preview",
482
482
  "preview.failed": "The preview could not be displayed.",
483
483
  "preview.title": "Preview",
484
+ "proactive.assistantPrompt": "Help me with this AI suggestion about {{entityType}} {{entityId}}: \"{{title}}\". {{why}}",
485
+ "proactive.card.actionFailed": "That didn't work. Try again, or open it yourself.",
486
+ "proactive.card.actionUnavailable": "This action isn't available any more.",
487
+ "proactive.card.aiBadge": "AI suggestion",
488
+ "proactive.card.dismiss": "Dismiss",
489
+ "proactive.card.dismissFailed": "Couldn't dismiss this suggestion. Try again.",
490
+ "proactive.card.snoozeDay": "Snooze 1 day",
491
+ "proactive.card.snoozeFailed": "Couldn't snooze this suggestion. Try again.",
492
+ "proactive.card.snoozeWeek": "Snooze 1 week",
493
+ "proactive.count.many": "{{count}} AI suggestions",
494
+ "proactive.count.none": "No AI suggestions",
495
+ "proactive.count.one": "1 AI suggestion",
496
+ "proactive.inbox.button": "Suggestions",
497
+ "proactive.inbox.buttonWithCount": "Suggestions ({{count}})",
498
+ "proactive.inbox.empty": "No suggestions right now. When the assistant finds something worth a look, it shows up here.",
499
+ "proactive.inbox.title": "Suggestions",
500
+ "proactive.pin.cardLabel": "AI suggestion",
501
+ "proactive.pin.label": "AI suggestion: {{title}}",
502
+ "proactive.settings.consent": "When this is on, the assistant looks through {{product}} in the background to find problems and opportunities. It reads as you and only reads: it never changes anything, and every suggestion waits for you to act on it.",
503
+ "proactive.settings.consentUntil": "Your permission lasts until {{date}}. Turning this off withdraws it at once.",
504
+ "proactive.settings.frequency.daily": "In a daily digest",
505
+ "proactive.settings.frequency.immediate": "As they come",
506
+ "proactive.settings.frequency.weekly": "In a weekly digest",
507
+ "proactive.settings.frequencyLegend": "When you're away, send suggestions",
508
+ "proactive.settings.frequencyUnavailable": "Saved. The delivery choice can't be stored yet, so suggestions arrive as they come.",
509
+ "proactive.settings.loadFailed": "Your suggestion settings couldn't be loaded.",
510
+ "proactive.settings.loading": "Loading your suggestion settings…",
511
+ "proactive.settings.productFallback": "this app",
512
+ "proactive.settings.quietHours": "Quiet hours and delivery channels",
513
+ "proactive.settings.retry": "Try again",
514
+ "proactive.settings.save": "Save",
515
+ "proactive.settings.saveFailed": "Your settings couldn't be saved. Try again.",
516
+ "proactive.settings.saved": "Saved.",
517
+ "proactive.settings.saving": "Saving…",
518
+ "proactive.settings.title": "Proactive suggestions",
519
+ "proactive.settings.toggle": "Let the assistant look for suggestions",
520
+ "proactive.severity.high": "High",
521
+ "proactive.severity.low": "Low",
522
+ "proactive.severity.medium": "Medium",
523
+ "proactive.severity.urgent": "Urgent",
484
524
  "sheet.collapse": "Shrink the assistant",
485
525
  "sheet.expand": "Expand the assistant",
486
526
  "speech.codeBlock": "Code block",
@@ -0,0 +1,67 @@
1
+ import { ReactNode } from 'react';
2
+ import { ApolloClient } from '@apollo/client';
3
+ import { BuiltInActionOptions, ProactiveActionHandler } from './actions';
4
+ import { SuggestionAnchorAdapter } from './adapters';
5
+ import { ProactiveTransport } from './transport';
6
+ import { ProactiveActivityEntity } from './types';
7
+ export interface ProactiveProviderProps {
8
+ /** Product id. Default: the enclosing `AssistantProductProvider`'s `product`. */
9
+ product?: string;
10
+ /**
11
+ * The product's action handlers by action type, each made with
12
+ * `defineProactiveAction`. `navigate` and `open-in-assistant` are built in and
13
+ * cannot be replaced; `review-proposal` may be given here or via
14
+ * `reviewProposal`.
15
+ */
16
+ actions?: Readonly<Record<string, ProactiveActionHandler>>;
17
+ /** The product router: receives a safe in-app path. Default: `navigateInApp`. */
18
+ navigate?: (path: string) => void;
19
+ /** May a `navigate` action open this path? Default: any safe in-app path. */
20
+ isAllowedRoute?: (path: string) => boolean;
21
+ /** Handles `review-proposal` until the shared decision card (BOFF-9989) exists. */
22
+ reviewProposal?: BuiltInActionOptions['reviewProposal'];
23
+ /**
24
+ * Opens the assistant with a prompt. Default: the shared assistant overlay
25
+ * (`openFull`) plus the store's `submitPrompt`. Without either, the
26
+ * `open-in-assistant` action is not offered.
27
+ */
28
+ openAssistant?: (prompt: string) => void;
29
+ /** Render adapters by entity type, registered while the provider is mounted. */
30
+ anchorAdapters?: Readonly<Record<string, SuggestionAnchorAdapter>>;
31
+ /** Inline comments shown at once (the interruption budget). Default 3. */
32
+ maxVisiblePins?: number;
33
+ /** Render inline comments at all. Default true; false leaves only the inbox. */
34
+ inlinePins?: boolean;
35
+ /**
36
+ * The entity the user has open. Default: `entityType` / `entityId` from the
37
+ * product's `gatherPageContext()`.
38
+ */
39
+ getActivityEntity?: () => ProactiveActivityEntity | null;
40
+ /** The signed-in user's id; with it, new suggestions also arrive through `notificationReceived`. */
41
+ userId?: string | null;
42
+ /** Gateway clients. Default: the shell's `GatewayContext`. */
43
+ globalClient?: ApolloClient;
44
+ workspaceClient?: ApolloClient;
45
+ /**
46
+ * A complete transport, replacing the Apollo one (tests, custom hosts). It
47
+ * owns its own authentication: the provider does not wait for the shell's
48
+ * access token before using it.
49
+ */
50
+ transport?: ProactiveTransport;
51
+ children?: ReactNode;
52
+ }
53
+ /**
54
+ * Mount once per product shell; see the module comment. Reads the two feature
55
+ * flags (both default OFF) and renders the runtime with the answer.
56
+ */
57
+ export declare function ProactiveProvider(props: ProactiveProviderProps): import('react').JSX.Element;
58
+ export interface ProactiveRuntimeProps extends ProactiveProviderProps {
59
+ /** Both proactive feature flags are on for the product. */
60
+ flagsOn: boolean;
61
+ }
62
+ /**
63
+ * The provider without its flag lookup. ★ Not part of the package entry: only
64
+ * `ProactiveProvider` is, so a product cannot switch the module on past its
65
+ * flags. The tests drive it directly.
66
+ */
67
+ export declare function ProactiveRuntime({ flagsOn, product: productProp, actions, navigate, isAllowedRoute, reviewProposal, openAssistant, anchorAdapters, maxVisiblePins, inlinePins, getActivityEntity, userId, globalClient, workspaceClient, transport: transportProp, children, }: ProactiveRuntimeProps): import('react').JSX.Element;
@@ -0,0 +1,128 @@
1
+ import { useAssistantTr as e } from "../assistant/i18n.js";
2
+ import { useAssistantProductOrNull as t } from "../assistant/product.js";
3
+ import { useSafeGateway as n } from "../graphql/GatewayContext.js";
4
+ import { useHasAuthToken as r } from "../graphql/useHasAuthToken.js";
5
+ import { readActivityEntity as i } from "./activity.js";
6
+ import { registerSuggestionAnchorAdapter as a } from "./adapters.js";
7
+ import { clampPinBudget as o, orderSuggestions as s } from "./budget.js";
8
+ import { ProactiveContextProvider as c } from "./context.js";
9
+ import { useProactiveFlagsEnabled as l } from "./flags.js";
10
+ import { PROACTIVE_PRODUCT_PATTERN as u } from "./metadata.js";
11
+ import { createApolloProactiveTransport as d } from "./transport.js";
12
+ import { SuggestionAnchorsLayer as f } from "./ui/SuggestionAnchorsLayer.js";
13
+ import { useActivityReporting as p, useProactiveSession as m } from "./useProactiveSession.js";
14
+ import { useSaveSettings as h, useSuggestionControls as g } from "./useSuggestionControls.js";
15
+ import { useCallback as _, useEffect as v, useMemo as y, useRef as b, useState as x } from "react";
16
+ import { jsx as S, jsxs as C } from "react/jsx-runtime";
17
+ // src/shared/proactive/ProactiveProvider.tsx
18
+ function w(e) {
19
+ return typeof e == "string" && u.test(e) ? e : "";
20
+ }
21
+ function T(e) {
22
+ let n = t(), r = l(w(e.product ?? n?.product));
23
+ return /* @__PURE__ */ S(D, {
24
+ ...e,
25
+ flagsOn: r
26
+ });
27
+ }
28
+ function E(e, t, r, i) {
29
+ let a = n(), o = t ?? a?.globalClient ?? null, s = r ?? a?.workspaceClient ?? null;
30
+ return y(() => e || (!o || !s ? null : d({
31
+ globalClient: o,
32
+ workspaceClient: s,
33
+ userId: i ?? null
34
+ })), [
35
+ e,
36
+ o,
37
+ s,
38
+ i
39
+ ]);
40
+ }
41
+ function D({ flagsOn: n, product: l, actions: u, navigate: d, isAllowedRoute: b, reviewProposal: x, openAssistant: T, anchorAdapters: D, maxVisiblePins: k, inlinePins: A = !0, getActivityEntity: j, userId: M, globalClient: N, workspaceClient: P, transport: F, children: I }) {
42
+ let L = t(), R = w(l ?? L?.product), z = r(), B = e(), V = E(F, N, P, M), H = m({
43
+ active: n && V !== null && (F !== void 0 || z),
44
+ product: R,
45
+ transport: V
46
+ }), U = H.status === "ready", W = L?.gatherPageContext, G = _(() => {
47
+ try {
48
+ return j ? j() : i(W?.());
49
+ } catch {
50
+ return null;
51
+ }
52
+ }, [j, W]);
53
+ p({
54
+ enabled: U,
55
+ sessionKey: H.sessionKey,
56
+ product: R,
57
+ transport: V,
58
+ readEntity: G
59
+ });
60
+ let K = g({
61
+ product: R,
62
+ transport: V,
63
+ session: H,
64
+ tr: B,
65
+ actions: u,
66
+ navigate: d,
67
+ isAllowedRoute: b,
68
+ reviewProposal: x,
69
+ openAssistant: T
70
+ }), q = h(R, V, H);
71
+ v(() => {
72
+ if (!D) return;
73
+ let e = Object.entries(D).map(([e, t]) => a(e, t));
74
+ return () => {
75
+ for (let t of e) t();
76
+ };
77
+ }, [D]);
78
+ let { reloadSettings: J, reloadList: Y } = H, X = _(() => {
79
+ J(), Y();
80
+ }, [J, Y]), Z = y(() => s(H.suggestions), [H.suggestions]), Q = o(k), $ = y(() => ({
81
+ product: R,
82
+ status: H.status,
83
+ settings: H.settings,
84
+ suggestions: U ? Z : [],
85
+ controls: K,
86
+ maxVisiblePins: Q,
87
+ saveSettings: q,
88
+ refresh: X
89
+ }), [
90
+ R,
91
+ H.status,
92
+ H.settings,
93
+ U,
94
+ Z,
95
+ K,
96
+ Q,
97
+ q,
98
+ X
99
+ ]);
100
+ return /* @__PURE__ */ C(c, {
101
+ value: $,
102
+ children: [
103
+ I,
104
+ U ? /* @__PURE__ */ S(O, {
105
+ count: H.listLoaded ? Z.length : null,
106
+ tr: K.tr
107
+ }) : null,
108
+ U && A ? /* @__PURE__ */ S(f, {
109
+ suggestions: Z,
110
+ controls: K,
111
+ maxVisiblePins: Q
112
+ }) : null
113
+ ]
114
+ });
115
+ }
116
+ function O({ count: e, tr: t }) {
117
+ let [n, r] = x(""), i = b(null);
118
+ return v(() => {
119
+ e !== null && (i.current !== null && i.current !== e && r(e === 0 ? t("proactive.count.none", "No AI suggestions") : e === 1 ? t("proactive.count.one", "1 AI suggestion") : t("proactive.count.many", "{{count}} AI suggestions", { count: e })), i.current = e);
120
+ }, [e, t]), /* @__PURE__ */ S("div", {
121
+ "aria-live": "polite",
122
+ "aria-atomic": "true",
123
+ className: "sr-only",
124
+ "data-agent": "deny",
125
+ children: n
126
+ });
127
+ }
128
+ export { T as ProactiveProvider, D as ProactiveRuntime };
@@ -0,0 +1,101 @@
1
+ import { z } from 'zod';
2
+ import { ProactiveSuggestion, ProactiveSuggestionAction } from './types';
3
+ declare const PROACTIVE_ACTION_BRAND: unique symbol;
4
+ /** What a handler is given when its action is clicked. */
5
+ export interface ProactiveActionContext {
6
+ readonly product: string;
7
+ readonly suggestion: ProactiveSuggestion;
8
+ readonly action: ProactiveSuggestionAction;
9
+ /** Open an in-app path through the product's router. False when the path is refused. */
10
+ navigate(path: string): boolean;
11
+ /** Open the assistant and send `prompt` as the user's own, visible message. */
12
+ openInAssistant(prompt: string): boolean;
13
+ }
14
+ /** What a product writes: an argument schema and the code that runs on click. */
15
+ export interface ProactiveActionSpec<TArgs> {
16
+ /** Validates the action's `args`; the action is hidden when they do not match. */
17
+ args: z.ZodType<TArgs>;
18
+ run(args: TArgs, context: ProactiveActionContext): void | Promise<void>;
19
+ }
20
+ /**
21
+ * A registered action handler. Built only by {@link defineProactiveAction}, so
22
+ * every handler validates its arguments the same way.
23
+ */
24
+ export interface ProactiveActionHandler {
25
+ readonly [PROACTIVE_ACTION_BRAND]: true;
26
+ /** Do these arguments validate? */
27
+ accepts(args: unknown): boolean;
28
+ /** Validate, then run. Throws {@link ProactiveActionArgsError} on invalid arguments. */
29
+ execute(args: unknown, context: ProactiveActionContext): Promise<void>;
30
+ }
31
+ /** Action handlers by action type. */
32
+ export type ProactiveActionRegistry = Readonly<Record<string, ProactiveActionHandler>>;
33
+ export declare class ProactiveActionArgsError extends Error {
34
+ constructor(type: string);
35
+ }
36
+ /** Wrap a product's action so the registry can run it. */
37
+ export declare function defineProactiveAction<TArgs>(spec: ProactiveActionSpec<TArgs>): ProactiveActionHandler;
38
+ /** Is `value` a handler made by {@link defineProactiveAction}? */
39
+ export declare function isProactiveActionHandler(value: unknown): value is ProactiveActionHandler;
40
+ export declare const NAVIGATE_ARGS: z.ZodObject<{
41
+ path: z.ZodString;
42
+ }, z.core.$strict>;
43
+ export declare const OPEN_IN_ASSISTANT_ARGS: z.ZodObject<{
44
+ entityType: z.ZodString;
45
+ entityId: z.ZodString;
46
+ prompt: z.ZodOptional<z.ZodString>;
47
+ }, z.core.$strict>;
48
+ export declare const REVIEW_PROPOSAL_ARGS: z.ZodObject<{
49
+ proposalId: z.ZodString;
50
+ }, z.core.$strict>;
51
+ export type NavigateActionArgs = z.infer<typeof NAVIGATE_ARGS>;
52
+ export type OpenInAssistantActionArgs = z.infer<typeof OPEN_IN_ASSISTANT_ARGS>;
53
+ export type ReviewProposalActionArgs = z.infer<typeof REVIEW_PROPOSAL_ARGS>;
54
+ /** The built-in types a product may not replace (only configure). */
55
+ export declare const RESERVED_ACTION_TYPES: readonly string[];
56
+ export interface BuiltInActionOptions {
57
+ /**
58
+ * May a `navigate` action open this path? Default: any safe in-app path. A
59
+ * product narrows it to the routes it is happy to be sent to.
60
+ */
61
+ isAllowedRoute?: (path: string) => boolean;
62
+ /**
63
+ * The text sent to the assistant when an `open-in-assistant` action carries no
64
+ * `prompt` of its own.
65
+ */
66
+ defaultAssistantPrompt: (suggestion: ProactiveSuggestion) => string;
67
+ /**
68
+ * Is there an assistant to open? Default true. False leaves
69
+ * `open-in-assistant` without a handler, so such actions are not offered.
70
+ */
71
+ canOpenAssistant?: boolean;
72
+ /**
73
+ * Handles `review-proposal` until the BOFF-9989 decision card exists. Absent,
74
+ * the type has no handler and such actions are not offered.
75
+ */
76
+ reviewProposal?: (proposalId: string, context: ProactiveActionContext) => void | Promise<void>;
77
+ }
78
+ /** The built-in handlers, configured for one product. */
79
+ export declare function createBuiltInActions(options: BuiltInActionOptions): ProactiveActionRegistry;
80
+ /**
81
+ * The registry in force: the built-ins plus the product's handlers. A product
82
+ * entry for a reserved built-in (`navigate`, `open-in-assistant`) is ignored, and
83
+ * so is anything not made by {@link defineProactiveAction}; both are reported to
84
+ * the console once per call.
85
+ */
86
+ export declare function mergeActionRegistries(builtIns: ProactiveActionRegistry, product: Readonly<Record<string, unknown>> | undefined): ProactiveActionRegistry;
87
+ /** The actions of a suggestion that can run here: a known type with valid arguments. */
88
+ export declare function offeredActions(suggestion: ProactiveSuggestion, registry: ProactiveActionRegistry): ProactiveSuggestionAction[];
89
+ export type ProactiveActionOutcome = {
90
+ status: 'done';
91
+ } | {
92
+ status: 'unavailable';
93
+ } | {
94
+ status: 'invalid-args';
95
+ } | {
96
+ status: 'failed';
97
+ error: unknown;
98
+ };
99
+ /** Run one action of a suggestion through the registry. Never throws. */
100
+ export declare function runProactiveAction(registry: ProactiveActionRegistry, context: ProactiveActionContext): Promise<ProactiveActionOutcome>;
101
+ export {};
@@ -0,0 +1,71 @@
1
+ import { isSafeInAppPath as e } from "../navigation/inAppPath.js";
2
+ import { z as t } from "zod";
3
+ // src/shared/proactive/actions.ts
4
+ var n = Symbol("burdenoff.proactive.action"), r = class extends Error {
5
+ constructor(e) {
6
+ super(`The arguments of this "${e}" action are not valid.`), this.name = "ProactiveActionArgsError";
7
+ }
8
+ };
9
+ function i(e) {
10
+ return {
11
+ [n]: !0,
12
+ accepts: (t) => e.args.safeParse(t).success,
13
+ execute: async (t, n) => {
14
+ let i = e.args.safeParse(t);
15
+ if (!i.success) throw new r(n.action.type);
16
+ await e.run(i.data, n);
17
+ }
18
+ };
19
+ }
20
+ function a(e) {
21
+ return typeof e == "object" && !!e && e[n] === !0;
22
+ }
23
+ var o = t.string().trim().min(1).max(255), s = t.string().max(1e3).regex(/^\/(?!\/)\S*$/).refine(e), c = t.strictObject({ path: s }), l = t.strictObject({
24
+ entityType: o,
25
+ entityId: o,
26
+ prompt: t.string().trim().min(1).max(400).optional()
27
+ }), u = t.strictObject({ proposalId: o }), d = ["navigate", "open-in-assistant"];
28
+ function f(e) {
29
+ let t = e.isAllowedRoute ?? (() => !0), n = { navigate: i({
30
+ args: c.refine((e) => t(e.path)),
31
+ run: (e, t) => {
32
+ t.navigate(e.path);
33
+ }
34
+ }) };
35
+ e.canOpenAssistant !== !1 && (n["open-in-assistant"] = i({
36
+ args: l,
37
+ run: (t, n) => {
38
+ n.openInAssistant(t.prompt ?? e.defaultAssistantPrompt(n.suggestion));
39
+ }
40
+ }));
41
+ let r = e.reviewProposal;
42
+ return r && (n["review-proposal"] = i({
43
+ args: u,
44
+ run: (e, t) => r(e.proposalId, t)
45
+ })), n;
46
+ }
47
+ function p(e, t) {
48
+ let n = { ...e };
49
+ for (let [e, r] of Object.entries(t ?? {})) d.includes(e) ? console.warn(`[proactive] The "${e}" action is built in and cannot be replaced; configure it through the provider props instead.`) : a(r) ? n[e] = r : console.warn(`[proactive] The "${e}" action handler was not made with defineProactiveAction and is ignored.`);
50
+ return n;
51
+ }
52
+ function m(e, t) {
53
+ return e.actions.filter((e) => {
54
+ let n = Object.hasOwn(t, e.type) ? t[e.type] : void 0;
55
+ return n !== void 0 && n.accepts(e.args);
56
+ });
57
+ }
58
+ async function h(e, t) {
59
+ let { action: n } = t, i = Object.hasOwn(e, n.type) ? e[n.type] : void 0;
60
+ if (!i) return { status: "unavailable" };
61
+ if (!i.accepts(n.args)) return { status: "invalid-args" };
62
+ try {
63
+ return await i.execute(n.args, t), { status: "done" };
64
+ } catch (e) {
65
+ return e instanceof r ? { status: "invalid-args" } : {
66
+ status: "failed",
67
+ error: e
68
+ };
69
+ }
70
+ }
71
+ export { c as NAVIGATE_ARGS, l as OPEN_IN_ASSISTANT_ARGS, r as ProactiveActionArgsError, d as RESERVED_ACTION_TYPES, u as REVIEW_PROPOSAL_ARGS, f as createBuiltInActions, i as defineProactiveAction, a as isProactiveActionHandler, p as mergeActionRegistries, m as offeredActions, h as runProactiveAction };
@@ -0,0 +1,27 @@
1
+ import { ProactiveActivityEntity } from './types';
2
+ export declare const ACTIVITY_DEBOUNCE_MS = 2000;
3
+ /**
4
+ * The entity in a product's page context (`gatherPageContext()`), or null. Only
5
+ * `entityType` and `entityId` are read, and only values that match the report's
6
+ * strict patterns are kept.
7
+ */
8
+ export declare function readActivityEntity(pageContext: unknown): ProactiveActivityEntity | null;
9
+ /** A stable key for an entity (or for "no entity"). */
10
+ export declare function activityKey(entity: ProactiveActivityEntity | null): string;
11
+ export interface ActivityReporterOptions {
12
+ report: (entity: ProactiveActivityEntity | null) => Promise<void>;
13
+ /** Told when a report fails; the reporter keeps going unless `stop()` is called. */
14
+ onError?: (error: unknown) => void;
15
+ debounceMs?: number;
16
+ setTimer?: (callback: () => void, ms: number) => unknown;
17
+ clearTimer?: (handle: unknown) => void;
18
+ }
19
+ export interface ActivityReporter {
20
+ /** Report the session start, with the entity open now (if any). Once. */
21
+ start(entity: ProactiveActivityEntity | null): void;
22
+ /** The entity the user has open now; reported after the debounce if it changed. */
23
+ update(entity: ProactiveActivityEntity | null): void;
24
+ /** Stop for good: cancels a pending report and ignores every later call. */
25
+ stop(): void;
26
+ }
27
+ export declare function createActivityReporter(options: ActivityReporterOptions): ActivityReporter;
@@ -0,0 +1,37 @@
1
+ import { ACTIVITY_ENTITY_ID_PATTERN as e, ACTIVITY_ENTITY_TYPE_PATTERN as t } from "./operations.js";
2
+ // src/shared/proactive/activity.ts
3
+ var n = 2e3;
4
+ function r(n) {
5
+ if (!n || typeof n != "object") return null;
6
+ let { entityType: r, entityId: i } = n;
7
+ return typeof r != "string" || typeof i != "string" || !t.test(r) || !e.test(i) ? null : {
8
+ entityType: r,
9
+ entityId: i
10
+ };
11
+ }
12
+ function i(e) {
13
+ return e ? `${e.entityType}\u0000${e.entityId}` : "";
14
+ }
15
+ function a(e) {
16
+ let t = e.debounceMs ?? 2e3, n = e.setTimer ?? ((e, t) => setTimeout(e, t)), r = e.clearTimer ?? ((e) => clearTimeout(e)), a = !1, o = !1, s = null, c = null, l = null, u = (t) => {
17
+ s = i(t), e.report(t).catch((t) => e.onError?.(t));
18
+ }, d = () => {
19
+ l !== null && r(l), l = null, c = null;
20
+ };
21
+ return {
22
+ start(e) {
23
+ a || o || (a = !0, u(e));
24
+ },
25
+ update(e) {
26
+ if (!a || o) return;
27
+ let r = i(e);
28
+ r !== c && (d(), r !== s && e !== null && (c = r, l = n(() => {
29
+ l = null, c = null, !o && r !== s && u(e);
30
+ }, t)));
31
+ },
32
+ stop() {
33
+ o = !0, d();
34
+ }
35
+ };
36
+ }
37
+ export { n as ACTIVITY_DEBOUNCE_MS, i as activityKey, a as createActivityReporter, r as readActivityEntity };
@@ -0,0 +1,54 @@
1
+ import { ProactiveActionOutcome } from './actions';
2
+ import { AssistantTr } from '../assistant/i18n';
3
+ import { ProactiveAnchor, ProactiveSnoozeDuration, ProactiveSuggestion, ProactiveSuggestionAction } from './types';
4
+ /**
5
+ * What a card needs to render a suggestion and act on it. The provider builds
6
+ * one and passes it to adapters and to its own components; an adapter's tree
7
+ * may sit outside the provider, so nothing here is read from React context.
8
+ */
9
+ export interface SuggestionControls {
10
+ /** Translate a relative assistant key (the provider's product namespace). */
11
+ tr: AssistantTr;
12
+ /** Whether snoozing is available (the notification service supports it). */
13
+ canSnooze: boolean;
14
+ /** The actions that can run here: known type, valid arguments. */
15
+ offeredActions(suggestion: ProactiveSuggestion): readonly ProactiveSuggestionAction[];
16
+ /** Run an action. Call ONLY from a person's click. */
17
+ runAction(suggestion: ProactiveSuggestion, action: ProactiveSuggestionAction): Promise<ProactiveActionOutcome>;
18
+ /** Dismiss (archive) a suggestion. Resolves false when it failed. */
19
+ dismiss(suggestion: ProactiveSuggestion): Promise<boolean>;
20
+ /** Snooze a suggestion. Resolves false when it failed. */
21
+ snooze(suggestion: ProactiveSuggestion, duration: ProactiveSnoozeDuration): Promise<boolean>;
22
+ /** The card was opened: the suggestion counts as read. Best-effort. */
23
+ markSeen(suggestion: ProactiveSuggestion): void;
24
+ }
25
+ export interface SuggestionAnchorAdapter {
26
+ /**
27
+ * Can the adapter show this anchor right now (the node is on the canvas)?
28
+ * Absent: always. A suggestion it cannot show does not use a budget slot.
29
+ */
30
+ canResolve?(anchor: ProactiveAnchor): boolean;
31
+ /**
32
+ * The suggestions to render for this entity type, already budgeted and
33
+ * ordered. An empty list means: show none. Called again on every change.
34
+ */
35
+ update(suggestions: readonly ProactiveSuggestion[], controls: SuggestionControls): void;
36
+ }
37
+ /**
38
+ * Register an adapter for `entityType`. Newest wins while several are
39
+ * registered (a route transition mounts the next page before the old one
40
+ * cleans up); the returned function removes exactly this registration.
41
+ */
42
+ export declare function registerSuggestionAnchorAdapter(entityType: string, adapter: SuggestionAnchorAdapter): () => void;
43
+ /** The adapter in force for an entity type, or undefined. */
44
+ export declare function getSuggestionAnchorAdapter(entityType: string): SuggestionAnchorAdapter | undefined;
45
+ /** Every entity type that has an adapter. */
46
+ export declare function listSuggestionAnchorAdapterTypes(): string[];
47
+ /** Be told when an adapter is registered or removed. Returns the unsubscribe. */
48
+ export declare function subscribeSuggestionAnchorAdapters(listener: () => void): () => void;
49
+ /** Changes whenever an adapter is registered or removed. */
50
+ export declare function getSuggestionAnchorAdapterVersion(): number;
51
+ /** Remove every adapter (tests). */
52
+ export declare function clearSuggestionAnchorAdapters(): void;
53
+ /** Controls that do nothing: what a removed adapter is last called with. */
54
+ export declare const EMPTY_CONTROLS: SuggestionControls;
@@ -0,0 +1,62 @@
1
+ // src/shared/proactive/adapters.ts
2
+ var e = Symbol.for("burdenoff.fe-libs.proactive.anchorAdapters.v1");
3
+ function t() {
4
+ let t = globalThis, n = t[e];
5
+ if (n && n.stacks instanceof Map && n.listeners instanceof Set) return typeof n.version != "number" && (n.version = 0), n;
6
+ let r = {
7
+ stacks: /* @__PURE__ */ new Map(),
8
+ listeners: /* @__PURE__ */ new Set(),
9
+ version: 0
10
+ };
11
+ return t[e] = r, r;
12
+ }
13
+ function n() {
14
+ let e = t();
15
+ e.version += 1;
16
+ for (let t of e.listeners) t();
17
+ }
18
+ function r(e, r) {
19
+ let { stacks: i } = t(), a = Symbol(e), o = i.get(e) ?? [];
20
+ o.push({
21
+ token: a,
22
+ adapter: r
23
+ }), i.set(e, o), n();
24
+ let s = !1;
25
+ return () => {
26
+ if (s) return;
27
+ s = !0;
28
+ let i = t().stacks.get(e);
29
+ if (!i) return;
30
+ let o = i.filter((e) => e.token !== a);
31
+ o.length === 0 ? t().stacks.delete(e) : t().stacks.set(e, o), r.update([], l), n();
32
+ };
33
+ }
34
+ function i(e) {
35
+ let n = t().stacks.get(e);
36
+ return n?.[n.length - 1]?.adapter;
37
+ }
38
+ function a() {
39
+ return [...t().stacks.keys()];
40
+ }
41
+ function o(e) {
42
+ let { listeners: n } = t();
43
+ return n.add(e), () => {
44
+ n.delete(e);
45
+ };
46
+ }
47
+ function s() {
48
+ return t().version;
49
+ }
50
+ function c() {
51
+ t().stacks.clear(), n();
52
+ }
53
+ var l = {
54
+ tr: (e, t, n) => n ? Object.entries(n).reduce((e, [t, n]) => e.split(`{{${t}}}`).join(String(n)), t) : t,
55
+ canSnooze: !1,
56
+ offeredActions: () => [],
57
+ runAction: () => Promise.resolve({ status: "unavailable" }),
58
+ dismiss: () => Promise.resolve(!1),
59
+ snooze: () => Promise.resolve(!1),
60
+ markSeen: () => {}
61
+ };
62
+ export { l as EMPTY_CONTROLS, c as clearSuggestionAnchorAdapters, i as getSuggestionAnchorAdapter, s as getSuggestionAnchorAdapterVersion, a as listSuggestionAnchorAdapterTypes, r as registerSuggestionAnchorAdapter, o as subscribeSuggestionAnchorAdapters };