@machinemetrics/mm-react-tools 5.2.4 → 5.4.0

package/dist/settings.d.ts

@@ -0,0 +1,130 @@
+export declare const DATE_RANGE_PRESETS: readonly ["today", "yesterday", "last7Days", "last30Days", "last90Days", "lastWeek", "last2Weeks", "lastMonth", "lastYear", "weekToDate", "monthToDate", "quarterToDate", "yearToDate"];
+export type DateRangePreset = (typeof DATE_RANGE_PRESETS)[number];
+/** Offered by the host when a dateRange setting has no `options`. */
+export declare const DEFAULT_DATE_RANGE_PRESETS: readonly ["today", "yesterday", "last7Days", "last30Days", "weekToDate", "monthToDate"];
+/**
+ * `start` and `end` are ISO instants on shop-day boundaries; `end` is
+ * exclusive. `startDay` and `endDay` are inclusive shop-day dates
+ * (yyyy-MM-dd) in the company's time zone.
+ */
+export interface DateRangeValue {
+    preset: DateRangePreset;
+    start: string;
+    end: string;
+    startDay: string;
+    endDay: string;
+}
+/** Valid: `true`, `null` or nothing. Invalid: the message, as a string or `{ message }`. */
+export type MMAppSettingValidateResult = true | string | {
+    message: string;
+} | null | undefined | void;
+export interface MMAppSettingOption {
+    label: string;
+    value: unknown;
+}
+export type MMAppSettingOptions = readonly MMAppSettingOption[] | ((args: {
+    filter?: string;
+}) => readonly MMAppSettingOption[] | Promise<readonly MMAppSettingOption[]>);
+interface MMAppSettingBase {
+    label?: string;
+    isRequired?: boolean;
+    helperText?: string;
+    visible?: boolean;
+    default?: unknown;
+    validate?: (args: {
+        value: any;
+    }) => MMAppSettingValidateResult | Promise<MMAppSettingValidateResult>;
+    [key: string]: unknown;
+}
+export interface MMAppInputSetting extends MMAppSettingBase {
+    type: 'input';
+    default?: string | number;
+}
+export interface MMAppSelectSetting extends MMAppSettingBase {
+    type: 'select';
+    options?: MMAppSettingOptions;
+    isMulti?: boolean;
+}
+export interface MMAppRadioSetting extends MMAppSettingBase {
+    type: 'radio';
+    options?: MMAppSettingOptions;
+}
+export interface MMAppThresholdField {
+    name: string;
+    label: string;
+    color?: string;
+    description?: string;
+    value?: number;
+    min?: number;
+    max?: number;
+}
+export interface MMAppThresholdsSetting extends MMAppSettingBase {
+    type: 'thresholds';
+    fields: MMAppThresholdField[];
+}
+export interface MMAppCustomSetting extends MMAppSettingBase {
+    type: 'custom';
+    url: string;
+    isMulti?: boolean;
+    drawerTitle?: string;
+    emptyLabel?: string;
+}
+/** The host resolves the chosen preset and delivers a {@link DateRangeValue}. */
+export interface MMAppDateRangeSetting extends MMAppSettingBase {
+    type: 'dateRange';
+    options?: readonly DateRangePreset[];
+    default?: DateRangePreset;
+    acceptGlobalOverride?: 'dateRange';
+}
+export type MMAppSettingConfig = MMAppInputSetting | MMAppSelectSetting | MMAppRadioSetting | MMAppThresholdsSetting | MMAppCustomSetting | MMAppDateRangeSetting;
+/**
+ * What `useMMAppSetting` accepts for any type but `dateRange`: any config, as
+ * before 5.3.0. The other `MMApp*Setting` types document the shapes hosts
+ * read, without enforcing them.
+ *
+ * @internal Exported only so a consumer's declarations can name the hook's
+ * signature.
+ */
+export interface MMAppLooseSetting {
+    type?: string | null | undefined;
+    [key: string]: any;
+}
+/**
+ * The part of every config read before its `type` is known: the `type` itself
+ * and the callbacks, so their parameters are typed whatever the setting.
+ *
+ * @internal Exported only so a consumer's declarations can name the hook's
+ * signature.
+ */
+export interface MMAppSettingCallbacks<T extends string> {
+    type?: T | null | undefined;
+    options?: readonly any[] | ((args: {
+        filter?: string;
+    }) => any) | null | false | undefined;
+    validate?: ((args: {
+        value: any;
+    }) => any) | null | false | undefined;
+}
+/**
+ * The config `useMMAppSetting` checks for a given `type`.
+ *
+ * @internal Exported only so a consumer's declarations can name the hook's
+ * signature.
+ */
+export type MMAppSettingConfigFor<T extends string> = T extends 'dateRange' ? MMAppDateRangeDeclaration : MMAppLooseSetting;
+/**
+ * {@link MMAppDateRangeSetting} without the open index signature, so a
+ * misspelled option is caught.
+ */
+export interface MMAppDateRangeDeclaration {
+    type: 'dateRange';
+    label?: string | undefined;
+    isRequired?: boolean | undefined;
+    helperText?: string | undefined;
+    visible?: boolean | undefined;
+    options?: readonly DateRangePreset[] | undefined;
+    default?: DateRangePreset | undefined;
+    acceptGlobalOverride?: 'dateRange' | undefined;
+}
+export {};
+//# sourceMappingURL=settings.d.ts.map

package/dist/settings.d.ts.map

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

package/dist/useMMAgent.d.ts

@@ -0,0 +1,69 @@
+/**
+ * App → Max, through the dashboard host. Use inside MMProvider.
+ *
+ *  - `report(kind, payload)`: background context for Max (`agent:event`).
+ *    Never the user's words.
+ *  - `ask(prompt, { newConversation })`: the user's own message to Max
+ *    (`agent:ask`), into the open conversation or a fresh one. It says
+ *    nothing about pages: an app that wants the page to the left of Max to
+ *    change asks, then navigates (in that order: the host only takes
+ *    messages from a frame that still exists, and navigating can unmount
+ *    it). The host holds the prompt until the new page is up.
+ *
+ * `ask` only works right after a user action (a click or key press): the
+ * browser's transient user activation. The host checks the same on its own
+ * window, so this check is for a clear error, not the security boundary.
+ */
+export declare const ASK_MAX_LENGTH = 4000;
+export declare const AGENT_ASK = "agent:ask";
+export declare const AGENT_ASK_CONSUMED = "agent:ask-consumed";
+export declare const AGENT_ASK_SOURCES: readonly ["app-gallery-builder", "app-gallery", "cml-renderer"];
+/** App-to-host request; the host supplies source and timestamp when forwarding. */
+export interface AgentAskPayload {
+    prompt: string;
+    newConversation?: boolean;
+}
+export interface AgentHostPrompt {
+    at: number;
+    prompt: string;
+    source: (typeof AGENT_ASK_SOURCES)[number];
+}
+export interface AgentAskConsumedPayload {
+    kind: 'newThreadPrompt' | 'agentAsk';
+    at: number;
+}
+export type AgentEventKind = 'app.error' | 'app.event' | 'app.context';
+/** Renderer event contract; threadId routes the event to its conversation. */
+export interface AgentEvent {
+    id: string;
+    kind: AgentEventKind;
+    at: string;
+    threadId: string;
+    app?: string;
+    /** Legacy alias; threadId is still required. */
+    thread?: string;
+    appId?: string;
+    surface?: 'page' | 'sidesheet' | 'widget' | 'tab' | 'tools';
+    message?: string;
+    summary?: string;
+    errors?: string[];
+    version?: number;
+    data?: unknown;
+}
+export type AgentEventPayload = Omit<AgentEvent, 'id' | 'kind' | 'at'>;
+export interface AskOptions {
+    /** Start a fresh conversation with this prompt as its first message. */
+    newConversation?: boolean;
+}
+export type AskResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'not-embedded' | 'no-user-action' | 'empty' | 'too-long';
+};
+export interface MMAgent {
+    report: (kind: AgentEventKind, payload: AgentEventPayload) => boolean;
+    ask: (prompt: string, options?: AskOptions) => AskResult;
+}
+export declare const useMMAgent: () => MMAgent;
+//# sourceMappingURL=useMMAgent.d.ts.map

package/dist/useMMAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMMAgent.d.ts","sourceRoot":"","sources":["../src/useMMAgent.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,OAAO,CAAC;AACnC,eAAO,MAAM,SAAS,cAAc,CAAC;AACrC,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AACvD,eAAO,MAAM,iBAAiB,iEAIpB,CAAC;AAEX,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,iBAAiB,GAAG,UAAU,CAAC;IACrC,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,WAAW,GAAG,aAAa,CAAC;AAEvE,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,KAAK,GAAG,OAAO,CAAC;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,UAAU,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC,CAAC;AASvE,MAAM,WAAW,UAAU;IACzB,wEAAwE;IACxE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,MAAM,SAAS,GACjB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,cAAc,GAAG,gBAAgB,GAAG,OAAO,GAAG,UAAU,CAAC;CAClE,CAAC;AAEN,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC;IACtE,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,KAAK,SAAS,CAAC;CAC1D;AAMD,eAAO,MAAM,UAAU,QAAO,OA6C7B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@machinemetrics/mm-react-tools",
-  "version": "5.2.4",
+  "version": "5.4.0",
   "description": "Components, hooks, and helper functions for writing React apps using MachineMetrics APIs.",
   "author": "machinemetrics",
   "license": "MIT",
@@ -27,6 +27,7 @@
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "type-check": "tsc --noEmit",
+    "type-check:consumer": "node scripts/check-consumer-types.mjs",
     "lint": "eslint . --color --max-warnings 19",
     "lint:fix": "eslint --max-warnings 19 . --color --fix",
     "prettier": "prettier --list-different '{*.(js|ts),**/*.(js|ts)}'",