@mj-biz-apps/common-entities 5.43.0 → 5.45.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './generated/entity_subclasses.js';
 export type { ActivityDetails, ActivitySyncConnectionSettings, ActivitySyncRuleFilter, } from './activity-json-types.js';
 export * from './business-day.js';
+export * from './party-signals.js';
 export * from './business-time-zone-engine.js';
 /**
  * This function is used to force the generated entities to be loaded. This is necessary because of the way that tree shaking works in webpack.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAA;AAC7C,YAAY,EACR,eAAe,EACf,8BAA8B,EAC9B,sBAAsB,GACzB,MAAM,uBAAuB,CAAC;AAE/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gCAAgC,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,SACpC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAA;AAC7C,YAAY,EACR,eAAe,EACf,8BAA8B,EAC9B,sBAAsB,GACzB,MAAM,uBAAuB,CAAC;AAE/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gCAAgC,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,SACpC"}

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from './generated/entity_subclasses.js';
 export * from './business-day.js';
+export * from './party-signals.js';
 export * from './business-time-zone-engine.js';
 /**
  * This function is used to force the generated entities to be loaded. This is necessary because of the way that tree shaking works in webpack.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAA;AAO7C,cAAc,mBAAmB,CAAC;AAClC,cAAc,gCAAgC,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB;AACrC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAA;AAO7C,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gCAAgC,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB;AACrC,CAAC"}

package/dist/party-signals.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The Party Signals contract — how an app tells the shared party pickers who its customers are.
+ *
+ * Common owns Organizations and People but cannot see the orders, contracts or sales schemas, and
+ * neither party carries a customer flag or a last-activity date. Rather than teach Common about
+ * every app, each app ships ONE MJ Query in the `Party Signals` category returning:
+ *
+ *   PartyKind       'organization' | 'person'
+ *   PartyID         the Common Organization or Person ID
+ *   Count           how many of the app's records name this party (orders, contracts, won deals)
+ *   LastActivityAt  the most recent date among them, or null
+ *
+ * and carrying `[signal: order|orders]` in its `Description` so a picker row can be labelled
+ * "4 orders" without knowing what an order is. The category IS the registry: nothing imports an
+ * app, and every client — Explorer, Skip, agents, MCP, reports — discovers the same queries
+ * through metadata and gets the same answer to "is this party a customer".
+ *
+ * This module is the contract plus the pure union of the rows. It has no MJ dependency at all, so
+ * the ranking it feeds can be tested without a database, a provider or Angular.
+ */
+export declare const PARTY_SIGNALS_CATEGORY = "Party Signals";
+export type PartyKind = 'organization' | 'person';
+/** One row as a signal query returns it. Loosely typed on purpose: it crosses a SQL boundary. */
+export interface PartySignalRow {
+    PartyKind: string;
+    PartyID: string;
+    Count: number;
+    LastActivityAt: string | Date | null;
+}
+/** One query's contribution: its rows plus the nouns its description declared. */
+export interface PartySignalSource {
+    QueryKey: string;
+    NounSingular: string;
+    NounPlural: string;
+    Rows: PartySignalRow[];
+}
+/** What one app says about one party. */
+export interface PartySignal {
+    QueryKey: string;
+    NounSingular: string;
+    NounPlural: string;
+    Count: number;
+    LastActivityAt: Date | null;
+}
+/** What every app together says about one party. */
+export interface PartyRosterEntry {
+    PartyID: string;
+    Kind: PartyKind;
+    Signals: PartySignal[];
+    TotalCount: number;
+    LastActivityAt: Date | null;
+}
+export interface SignalNouns {
+    NounSingular: string;
+    NounPlural: string;
+}
+/**
+ * Pull the chip nouns out of a query description. A query that forgets the marker still works;
+ * its rows are simply labelled "4 records", which is honest rather than wrong.
+ */
+export declare function ParseSignalNouns(description: string | null | undefined): SignalNouns;
+/** "4 orders", "1 order" — the text of one picker chip. */
+export declare function ChipText(signal: Pick<PartySignal, 'Count' | 'NounSingular' | 'NounPlural'>): string;
+/**
+ * Union every source into one entry per party.
+ *
+ * Party IDs are matched case-insensitively because GUIDs arrive in whichever case the provider
+ * and the query happened to produce, and two spellings of one organization would otherwise read
+ * as two customers — the exact defect this whole feature exists to stop showing people. The first
+ * spelling seen is the one kept, so it still matches the record it came from. Rows whose kind is
+ * outside the contract, or whose ID is blank, are dropped rather than trusted.
+ */
+export declare function MergePartySignalRows(sources: ReadonlyArray<PartySignalSource>): PartyRosterEntry[];
+//# sourceMappingURL=party-signals.d.ts.map

package/dist/party-signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"party-signals.d.ts","sourceRoot":"","sources":["../src/party-signals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,eAAO,MAAM,sBAAsB,kBAAkB,CAAC;AAEtD,MAAM,MAAM,SAAS,GAAG,cAAc,GAAG,QAAQ,CAAC;AAElD,iGAAiG;AACjG,MAAM,WAAW,cAAc;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;CACxC;AAED,kFAAkF;AAClF,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,cAAc,EAAE,CAAC;CAC1B;AAED,yCAAyC;AACzC,MAAM,WAAW,WAAW;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,IAAI,GAAG,IAAI,CAAC;CAC/B;AAED,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,IAAI,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACtB;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,CAMpF;AAED,2DAA2D;AAC3D,wBAAgB,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,cAAc,GAAG,YAAY,CAAC,GAAG,MAAM,CAEnG;AAmCD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,GAAG,gBAAgB,EAAE,CAgBlG"}

package/dist/party-signals.js

@@ -0,0 +1,94 @@
+/**
+ * The Party Signals contract — how an app tells the shared party pickers who its customers are.
+ *
+ * Common owns Organizations and People but cannot see the orders, contracts or sales schemas, and
+ * neither party carries a customer flag or a last-activity date. Rather than teach Common about
+ * every app, each app ships ONE MJ Query in the `Party Signals` category returning:
+ *
+ *   PartyKind       'organization' | 'person'
+ *   PartyID         the Common Organization or Person ID
+ *   Count           how many of the app's records name this party (orders, contracts, won deals)
+ *   LastActivityAt  the most recent date among them, or null
+ *
+ * and carrying `[signal: order|orders]` in its `Description` so a picker row can be labelled
+ * "4 orders" without knowing what an order is. The category IS the registry: nothing imports an
+ * app, and every client — Explorer, Skip, agents, MCP, reports — discovers the same queries
+ * through metadata and gets the same answer to "is this party a customer".
+ *
+ * This module is the contract plus the pure union of the rows. It has no MJ dependency at all, so
+ * the ranking it feeds can be tested without a database, a provider or Angular.
+ */
+export const PARTY_SIGNALS_CATEGORY = 'Party Signals';
+const SIGNAL_MARKER = /\[signal:\s*([^|\]]+)\|([^\]]+)\]/i;
+const DEFAULT_NOUNS = { NounSingular: 'record', NounPlural: 'records' };
+/**
+ * Pull the chip nouns out of a query description. A query that forgets the marker still works;
+ * its rows are simply labelled "4 records", which is honest rather than wrong.
+ */
+export function ParseSignalNouns(description) {
+    const match = SIGNAL_MARKER.exec(description ?? '');
+    if (!match) {
+        return { ...DEFAULT_NOUNS };
+    }
+    return { NounSingular: match[1].trim(), NounPlural: match[2].trim() };
+}
+/** "4 orders", "1 order" — the text of one picker chip. */
+export function ChipText(signal) {
+    return `${signal.Count} ${signal.Count === 1 ? signal.NounSingular : signal.NounPlural}`;
+}
+function toDate(value) {
+    if (!value) {
+        return null;
+    }
+    const date = value instanceof Date ? value : new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+function toKind(value) {
+    const kind = (value ?? '').trim().toLowerCase();
+    return kind === 'organization' || kind === 'person' ? kind : null;
+}
+function toCount(value) {
+    const count = Number(value);
+    return Number.isFinite(count) ? count : 0;
+}
+function addRow(entry, source, row) {
+    const at = toDate(row.LastActivityAt);
+    entry.Signals.push({
+        QueryKey: source.QueryKey,
+        NounSingular: source.NounSingular,
+        NounPlural: source.NounPlural,
+        Count: toCount(row.Count),
+        LastActivityAt: at,
+    });
+    entry.TotalCount += toCount(row.Count);
+    if (at && (!entry.LastActivityAt || at > entry.LastActivityAt)) {
+        entry.LastActivityAt = at;
+    }
+}
+/**
+ * Union every source into one entry per party.
+ *
+ * Party IDs are matched case-insensitively because GUIDs arrive in whichever case the provider
+ * and the query happened to produce, and two spellings of one organization would otherwise read
+ * as two customers — the exact defect this whole feature exists to stop showing people. The first
+ * spelling seen is the one kept, so it still matches the record it came from. Rows whose kind is
+ * outside the contract, or whose ID is blank, are dropped rather than trusted.
+ */
+export function MergePartySignalRows(sources) {
+    const byID = new Map();
+    for (const source of sources) {
+        for (const row of source.Rows) {
+            const kind = toKind(row.PartyKind);
+            const id = (row.PartyID ?? '').trim();
+            if (!kind || !id) {
+                continue;
+            }
+            const key = id.toLowerCase();
+            const entry = byID.get(key) ?? { PartyID: id, Kind: kind, Signals: [], TotalCount: 0, LastActivityAt: null };
+            addRow(entry, source, row);
+            byID.set(key, entry);
+        }
+    }
+    return [...byID.values()];
+}
+//# sourceMappingURL=party-signals.js.map

package/dist/party-signals.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mj-biz-apps/common-entities",
   "type": "module",
-  "version": "5.43.0",
+  "version": "5.45.0",
   "description": "MJ BizApps Common Entity Subclasses",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",