@indexnetwork/protocol 6.12.1-rc.404.1 → 6.14.0-rc.406.1

package/dist/opportunity/application/opportunity.tools.d.ts

@@ -0,0 +1,131 @@
+import type { DefineTool } from "../../shared/agent/tool.helpers.js";
+import type { OpportunityToolDeps } from "../../capabilities/opportunities.tools.port.js";
+export { buildOpportunityPresentation } from "./opportunity.card-presentation.js";
+import type { Opportunity } from "../../shared/interfaces/database.interface.js";
+import type { ConnectLinkKind } from "../../shared/interfaces/connect-link.interface.js";
+/**
+ * Pure status × role → ConnectLinkKind matrix.
+ *
+ * Returns the kind of short-link the viewer can act on directly, or `null` if
+ * no direct link makes sense for this combination. Non-null kinds map to:
+ *
+ * - `connect` — pending opp where viewer is a non-introducer party. Clicking
+ *   flips the opp to accepted and opens the chat with the counterpart.
+ * - `approve_introduction` — draft or latent opp where viewer is an unapproved
+ *   introducer. Clicking flips approved=true and triggers negotiation. The
+ *   `draft` case comes from `discover_opportunities` intro mode; the `latent`
+ *   case comes from background-discovered connector-flow cards surfaced in
+ *   `list_opportunities`. In both, status remains pre-send and the `/c/<code>`
+ *   link is the only MCP path to approve.
+ * - `outreach` — accepted opp where viewer is a non-introducer party.
+ *   Clicking opens the existing chat (no state change).
+ * - `send_direct` — draft or latent opp where viewer is a non-introducer
+ *   party. Issued by `discover_opportunities` in direct (no-introducer)
+ *   mode: the match has already passed evaluation, the row exists in
+ *   draft state, and the sender just needs to release it. Clicking flips
+ *   the opp straight to accepted and opens the chat with a greeting —
+ *   same handler path as `connect`. The counterpart's side sees the new
+ *   accepted opp and can engage or ignore.
+ */
+export declare function resolveActionableLinkKind(input: {
+    status: string;
+    viewerRole: string;
+    viewerApproved?: boolean;
+    viewerActedAt?: string | null;
+}): ConnectLinkKind | null;
+/**
+ * Build the agent-facing profile link for a counterpart — always the Index web
+ * profile URL with `?link_preview=false`. Returns `undefined` only if
+ * `frontendUrl` is not configured.
+ *
+ * The `?link_preview=false` hint is honored by chat-gateway runtimes (e.g.
+ * OpenClaw's Telegram delivery) that strip link previews when present in the
+ * URL; consistent placement matters more than Telegram's own handling.
+ *
+ * Trailing slashes on frontendUrl are stripped before concatenation.
+ */
+export declare function buildProfileUrl(counterpartUserId: string, frontendUrl: string | undefined): string | undefined;
+/**
+ * Build the deep-link to an opportunity's A2A negotiation trace
+ * (`/chat/:conversationId`) so users can see *what negotiation led to* the
+ * surfaced opportunity (EDG-50/EDG-51). Returns `undefined` when `frontendUrl`
+ * is unset or there is no negotiation conversation to link to.
+ *
+ * The `?link_preview=false` hint mirrors `buildProfileUrl` — chat-gateway
+ * runtimes (e.g. Telegram delivery) strip link previews when it is present.
+ * Trailing slashes on `frontendUrl` are stripped before concatenation.
+ */
+export declare function buildNegotiationUrl(conversationId: string | undefined, frontendUrl: string | undefined): string | undefined;
+/**
+ * Mint a short-link for `card` if the (status, viewerRole, viewerApproved)
+ * combination is actionable; mutate the card in place with `acceptUrl`,
+ * `profileUrl`, and `feedCategory`. No-op (and no DB call) if not actionable.
+ *
+ * Swallows mint errors after logging — the card is still returned without an
+ * `acceptUrl`, matching the prior `list_opportunities` resilience behavior.
+ */
+export declare function attachActionableLinks(card: Record<string, unknown> & {
+    opportunityId: string;
+    viewerRole: string;
+    status: string;
+}, opts: {
+    viewerId: string;
+    viewerApproved?: boolean;
+    viewerActedAt?: string | null;
+    counterpartUserId: string;
+    mintConnectLink: NonNullable<OpportunityToolDeps["mintConnectLink"]>;
+    frontendUrl: string | undefined;
+    preferredSurface?: 'telegram' | 'web';
+}): Promise<void>;
+/**
+ * Build minimal opportunity card data for chat without calling the LLM presenter.
+ * Uses only required fields from the opportunity record and counterpart name/avatar
+ * so list_opportunities and discovery return quickly.
+ *
+ * Note: narratorChip.text is generated via regex heuristics (narratorRemarkFromReasoning)
+ * rather than the OpportunityPresenter LLM. If narrator quality becomes an issue again,
+ * consider making this function async and delegating to OpportunityPresenter.presentHomeCard()
+ * which already produces a high-quality narratorRemark via LLM (used by the home graph
+ * and discovery pipeline). The trade-off is 5-20s latency per card.
+ *
+ * Exported for use in tests (opportunity.tools.spec.ts).
+ */
+export declare function buildMinimalOpportunityCard(opp: Opportunity, viewerId: string, counterpartUserId: string, counterpartName: string, counterpartAvatar: string | null, introducerName?: string | null, introducerAvatar?: string | null, viewerName?: string, secondPartyName?: string, secondPartyAvatar?: string | null, secondPartyUserId?: string, isCounterpartGhost?: boolean): {
+    opportunityId: string;
+    userId: string;
+    name: string;
+    avatar: string | null;
+    mainText: string;
+    cta: string;
+    headline: string;
+    primaryActionLabel: string;
+    secondaryActionLabel: string;
+    mutualIntentsLabel: string;
+    narratorChip: {
+        name: string;
+        text: string;
+        avatar?: string | null;
+        userId?: string;
+    };
+    viewerRole: string;
+    score: number | undefined;
+    status: string;
+    isGhost: boolean;
+    secondParty?: {
+        name: string;
+        avatar?: string | null;
+        userId?: string;
+    };
+};
+/**
+ * Stable, retry-classified error codes for `confirm_opportunity_delivery`.
+ *
+ * The plain `error()` envelope only carries a human message, which forced
+ * callers (the Hermes digest sweep) to treat every failure — permanent or
+ * transient — as retryable, and made "already delivered but never confirmed"
+ * impossible to distinguish from "opportunity deleted". Each code carries an
+ * explicit `retryable` flag so deterministic callers can retry transient
+ * failures and drop permanent ones instead of re-spamming the ledger.
+ */
+export type ConfirmDeliveryErrorCode = "unauthenticated" | "ledger_unavailable" | "invalid_opportunity_id" | "opportunity_not_found" | "not_authorized" | "confirm_failed";
+export declare function createOpportunityTools(defineTool: DefineTool, deps: OpportunityToolDeps): readonly [any, any, any, any, any, any];