@opencxh/domain 1.211.0 → 1.214.0

package/dist/platform/resource-source.d.ts

@@ -36,6 +36,10 @@ export declare const RESOURCE_RESOLVE_SERVICE = "resources.resolve";
  * items carry the conversation's key, the conversation knows nothing about work. Answering it
  * here rather than per consumer is what keeps the shell from growing an
  * `if (kind === "interaction")` per app that could be linked.
+ *
+ * The rows may be {@link RelatedResource}s, i.e. carry an `origin`. Answering with the plain
+ * summary stays valid; a consumer that wants to separate a link from a lead reads that field and
+ * treats its absence as "unknown, so not a stated link".
  */
 export declare const RESOURCE_ATTACHED_SERVICE = "resources.attached";
 /** One pointable resource, as the app that owns it shows it. */
@@ -106,3 +110,104 @@ export interface ResourceAttachedParams {
  * and this contract is read mostly on the client.
  */
 export declare function resourceKindOf(scopeKey: string): string;
+/**
+ * The same question, server-side: **what hangs on this key, and is that a fact or a guess.**
+ *
+ * The service-bus keys above are asked by a user with the app open. An AI tool, a playbook and a
+ * job have no client and no store, so they need the question over HTTP, and in one place: the hub
+ * in apps/context (`POST /resource/related`). It answers from two sources:
+ *
+ * - **linked** — a {@link Relation} row: somebody (or a tool) linked the two. One local indexed
+ *   read on the relation store, both directions, no protocol between apps.
+ * - **derived** — a row that merely shares a dossier key with the anchor (`domain:`, `mailto:`).
+ *   The hub fans `/provider/scope/related` out over the **existing `scope` provider role**: the
+ *   apps that own kinds already authorize there and already return {@link ScopeAuth.keys}.
+ *
+ * | Route | Body | Answer |
+ * |---|---|---|
+ * | `/provider/scope/related` | {@link RelatedResourceRequest} | {@link RelatedResourceResponse} |
+ * | `/provider/scope/read` | {@link ResourceReadRequest} | {@link ResourceReadResponse} |
+ *
+ * Both are app-to-app and optional: an app that does not implement them loses its own rows, never
+ * the answer. The hub resolves the anchor's dossier keys **once** (`authorizeIdentity`) and passes
+ * them along, so a fan-out over five apps still costs one authorization.
+ */
+export declare const SCOPE_RELATED_ROUTE = "/provider/scope/related";
+export declare const SCOPE_READ_ROUTE = "/provider/scope/read";
+/**
+ * One explicit link between two resources, stored by apps/context.
+ *
+ * **Two rows per link**, out and back, so "what hangs on this key" is one indexed query on
+ * `fromKey` in either direction instead of an `$or` no index serves. **One hop, never traversed:**
+ * this store cannot join or recurse, so a relation is read, not followed. Party matches (a shared
+ * domain, a shared address) are not relations; they stay dossier keys on the row.
+ */
+export interface Relation {
+    id: string;
+    organizationId: string;
+    fromKey: string;
+    toKey: string;
+    /**
+     * The relation and the party role in one vocabulary: `client` · `opposing` · `context` ·
+     * `blocks` · `blocked_by` · `relates` · `duplicates` · `attachment` · `party`. One field, no
+     * separate role column: "this company is the client" and "this item blocks that" are both a
+     * named arrow.
+     */
+    type: string;
+    /** Shared by the outbound and the inbound row; keeps unlinking one action. */
+    pairId: string;
+    /** How the inbound row identifies itself, so a UI can show "is blocked by". */
+    inverse?: boolean;
+    createdBy: string;
+    createdAt?: number;
+}
+/**
+ * What the hub asks one app. `scopeKey` is already authorized — the answering app must not
+ * re-gate it, but it must filter its own rows for the stamped acting identity.
+ */
+export interface RelatedResourceRequest {
+    /** The anchor: the thing the user (or the model) is standing on. */
+    scopeKey: string;
+    /**
+     * The anchor's dossier keys and the keys it is linked to, `scopeKey` included. An app matches
+     * its own indexed key column against this in one `$in`, and resolves the keys that name its
+     * own rows (`interaction:<id>`).
+     */
+    keys: string[];
+    /** Maximum rows this app may return. Absent = its own sensible cap. */
+    limit?: number;
+}
+/**
+ * One related row, and **why** it is related.
+ *
+ * `origin` is decided by the hub: a row the anchor has a {@link Relation} to is `linked`, any
+ * other match is `derived`. An app sets it only for a **structural** relation it owns and that
+ * no relation row expresses (a contact's employer via `companyId`). A consumer keeps the two
+ * apart: a model told "these are the linked conversations" reads a domain match as a fact.
+ */
+export interface RelatedResource extends ResourceSummary {
+    origin?: "linked" | "derived";
+    /** Why this row is here: the relation type (`client`), or the dossier key that matched. */
+    via?: string;
+}
+export interface RelatedResourceResponse {
+    /**
+     * Rows relevant to the asked key set, in both directions an app can answer:
+     * rows **identified by** one of the keys (resolution), and rows **carrying** one of them
+     * (the key match). One route for both, because to the answering app they are the same
+     * `$in` over the same indexed column.
+     */
+    rows: RelatedResource[];
+}
+/** Params for `/provider/scope/read`: one key, answered by the app that owns the kind. */
+export interface ResourceReadRequest {
+    scopeKey: string;
+}
+/**
+ * One resource as readable text — the generic counterpart of `read_work_item` /
+ * `list_activities`, so a caller with a bare key does not have to know which app's tool reads it.
+ */
+export interface ResourceReadResponse {
+    text: string;
+    title?: string;
+}

package/dist/platform/resource-source.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/text/triage.d.ts

@@ -11,3 +11,23 @@ export declare const SUMMARY_MIN_MESSAGES = 3;
 export declare const SUMMARY_MIN_LAST_CHARS = 600;
 /** True when the thread is long enough that a summary saves the reader scrolling. */
 export declare function isThreadLongEnough(messageCount: number, lastMessageChars: number): boolean;
+/** Headers that say something about bulk/automated origin. Nothing else is stored. */
+export declare const MAIL_HINT_HEADERS: string[];
+/** Graph and Gmail both hand us `{name,value}[]`; keep only the whitelist, lowercased. */
+export declare function pickMailHeaders(entries: {
+    name?: string;
+    value?: string;
+}[]): Record<string, string>;
+export type MailClass = "marketing" | "automated";
+/**
+ * Which bulk label an inbound mail deserves, if any. Headers first, sender/body
+ * regex as fallback. `automated` is checked first on purpose: an order
+ * confirmation carrying an unsubscribe footer is still automated, not marketing.
+ */
+export declare function classifyMail(p: {
+    from?: {
+        email: string;
+    };
+    body?: string;
+    headers?: Record<string, string>;
+}): MailClass | undefined;

package/dist/text/triage.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencxh/domain",
-  "version": "1.211.0",
+  "version": "1.214.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",