@agent-native/core 0.123.0 → 0.123.2

package/corpus/templates/crm/server/crm/provider-record-link.ts

@@ -0,0 +1,264 @@
+import { accessFilter } from "@agent-native/core/sharing";
+import { resolveWorkspaceConnectionForApp } from "@agent-native/core/workspace-connections";
+import { and, inArray } from "drizzle-orm";
+
+import { getDb, schema } from "../db/index.js";
+import {
+  isConnectedCrmProvider,
+  type ConnectedCrmProvider,
+} from "./adapter.js";
+
+const CRM_APP_ID = "crm";
+
+/**
+ * HubSpot addresses records by its fully-qualified object type id, not by the
+ * object name the CRM API takes. Custom objects already arrive shaped `2-1234`
+ * and pass straight through.
+ */
+const HUBSPOT_OBJECT_TYPE_IDS: Record<string, string> = {
+  contact: "0-1",
+  contacts: "0-1",
+  company: "0-2",
+  companies: "0-2",
+  deal: "0-3",
+  deals: "0-3",
+  ticket: "0-5",
+  tickets: "0-5",
+};
+
+export type ProviderRecordLinkUnavailableReason =
+  | "missing-portal-id"
+  | "unsupported-object-type"
+  | "invalid-remote-id"
+  | "missing-instance-url"
+  | "workspace-connection-unavailable";
+
+/**
+ * A link is either present or typed-absent with the reason. There is no
+ * empty-string or best-guess URL: a wrong deep link reads to the user as a
+ * working handoff and sends them to somebody else's record.
+ */
+export type ProviderRecordLink =
+  | { available: true; url: string }
+  | { available: false; reason: ProviderRecordLinkUnavailableReason };
+
+const HUBSPOT_PORTAL_ID = /^\d{1,20}$/;
+const HUBSPOT_OBJECT_TYPE_ID = /^\d{1,4}-\d{1,10}$/;
+const HUBSPOT_REMOTE_ID = /^[A-Za-z0-9_-]{1,64}$/;
+const SALESFORCE_OBJECT_API_NAME = /^[A-Za-z][A-Za-z0-9_]{0,79}$/;
+const SALESFORCE_RECORD_ID = /^[A-Za-z0-9]{15,18}$/;
+
+function hubSpotObjectTypeId(objectType: string): string | null {
+  const normalized = objectType.trim().toLowerCase();
+  if (HUBSPOT_OBJECT_TYPE_ID.test(normalized)) return normalized;
+  return HUBSPOT_OBJECT_TYPE_IDS[normalized] ?? null;
+}
+
+function salesforceOrigin(configured: string): string | null {
+  let url: URL;
+  try {
+    url = new URL(configured);
+  } catch {
+    return null;
+  }
+  const host = url.hostname.toLowerCase();
+  const trustedHost =
+    host === "salesforce.com" ||
+    host.endsWith(".salesforce.com") ||
+    host.endsWith(".force.com");
+  if (
+    url.protocol !== "https:" ||
+    !trustedHost ||
+    url.port ||
+    url.username ||
+    url.password
+  ) {
+    return null;
+  }
+  return url.origin;
+}
+
+/**
+ * Builds the upstream record URL a person can open to complete a change by
+ * hand. Pure so both providers stay covered by one test.
+ */
+export function buildProviderRecordUrl(input: {
+  provider: ConnectedCrmProvider;
+  objectType: string;
+  remoteId: string;
+  /** HubSpot portal id (`crm_connections.account_id`). */
+  portalId?: string | null;
+  /** Salesforce My Domain origin from the workspace connection config. */
+  instanceUrl?: string | null;
+}): ProviderRecordLink {
+  const remoteId = input.remoteId.trim();
+  if (input.provider === "hubspot") {
+    const portalId = input.portalId?.trim();
+    if (!portalId || !HUBSPOT_PORTAL_ID.test(portalId)) {
+      return { available: false, reason: "missing-portal-id" };
+    }
+    const objectTypeId = hubSpotObjectTypeId(input.objectType);
+    if (!objectTypeId) {
+      return { available: false, reason: "unsupported-object-type" };
+    }
+    if (!HUBSPOT_REMOTE_ID.test(remoteId)) {
+      return { available: false, reason: "invalid-remote-id" };
+    }
+    return {
+      available: true,
+      url: `https://app.hubspot.com/contacts/${portalId}/record/${objectTypeId}/${remoteId}`,
+    };
+  }
+
+  const configured = input.instanceUrl?.trim();
+  if (!configured) return { available: false, reason: "missing-instance-url" };
+  const origin = salesforceOrigin(configured);
+  if (!origin) return { available: false, reason: "missing-instance-url" };
+  const objectApiName = input.objectType.trim();
+  if (!SALESFORCE_OBJECT_API_NAME.test(objectApiName)) {
+    return { available: false, reason: "unsupported-object-type" };
+  }
+  if (!SALESFORCE_RECORD_ID.test(remoteId)) {
+    return { available: false, reason: "invalid-remote-id" };
+  }
+  return {
+    available: true,
+    url: `${origin}/lightning/r/${objectApiName}/${remoteId}/view`,
+  };
+}
+
+/**
+ * Everything a connection contributes to its records' links, resolved once.
+ * HubSpot's portal id is already mirrored on the CRM connection row; only
+ * Salesforce needs the workspace connection, which owns the My Domain origin.
+ */
+type ConnectionLinkContext =
+  | { portalId: string | null; instanceUrl?: undefined }
+  | { instanceUrl: string | null; portalId?: undefined }
+  | { unavailable: ProviderRecordLinkUnavailableReason };
+
+async function connectionLinkContext(input: {
+  provider: ConnectedCrmProvider;
+  accountId: string | null;
+  workspaceConnectionId: string | null;
+}): Promise<ConnectionLinkContext> {
+  if (input.provider === "hubspot") return { portalId: input.accountId };
+  const resolved = await resolveWorkspaceConnectionForApp({
+    appId: CRM_APP_ID,
+    provider: "salesforce",
+    ...(input.workspaceConnectionId
+      ? { connectionId: input.workspaceConnectionId }
+      : {}),
+  });
+  if (!resolved.available || !resolved.connection) {
+    return { unavailable: "workspace-connection-unavailable" };
+  }
+  const config = resolved.connection.config as
+    | Record<string, unknown>
+    | undefined;
+  const instanceUrl = ["instanceUrl", "instance_url", "salesforceInstanceUrl"]
+    .map((key) => config?.[key])
+    .find(
+      (value): value is string => typeof value === "string" && !!value.trim(),
+    );
+  return { instanceUrl: instanceUrl ?? null };
+}
+
+function linkFromContext(
+  context: ConnectionLinkContext,
+  record: {
+    provider: ConnectedCrmProvider;
+    objectType: string;
+    remoteId: string;
+  },
+): ProviderRecordLink {
+  if ("unavailable" in context) {
+    return { available: false, reason: context.unavailable };
+  }
+  return buildProviderRecordUrl({
+    provider: record.provider,
+    objectType: record.objectType,
+    remoteId: record.remoteId,
+    portalId: context.portalId ?? null,
+    instanceUrl: context.instanceUrl ?? null,
+  });
+}
+
+export async function resolveProviderRecordLink(input: {
+  provider: ConnectedCrmProvider;
+  objectType: string;
+  remoteId: string;
+  accountId: string | null;
+  workspaceConnectionId: string | null;
+}): Promise<ProviderRecordLink> {
+  return linkFromContext(await connectionLinkContext(input), input);
+}
+
+/**
+ * Bulk variant for list surfaces. Records with a native (or otherwise
+ * unconnected) provider are simply absent from the map — they have no upstream
+ * record to open.
+ */
+export async function resolveProviderRecordLinks(
+  recordIds: string[],
+): Promise<Map<string, ProviderRecordLink>> {
+  const links = new Map<string, ProviderRecordLink>();
+  const ids = [...new Set(recordIds)];
+  if (!ids.length) return links;
+  const db = getDb();
+  const records = await db
+    .select({
+      id: schema.crmRecords.id,
+      connectionId: schema.crmRecords.connectionId,
+      provider: schema.crmRecords.provider,
+      objectType: schema.crmRecords.objectType,
+      remoteId: schema.crmRecords.remoteId,
+    })
+    .from(schema.crmRecords)
+    .where(
+      and(
+        inArray(schema.crmRecords.id, ids),
+        accessFilter(schema.crmRecords, schema.crmRecordShares),
+      ),
+    );
+  const connectedRecords = records.filter((record) =>
+    isConnectedCrmProvider(record.provider),
+  );
+  if (!connectedRecords.length) return links;
+  const connections = await db
+    .select({
+      id: schema.crmConnections.id,
+      accountId: schema.crmConnections.accountId,
+      workspaceConnectionId: schema.crmConnections.workspaceConnectionId,
+    })
+    .from(schema.crmConnections)
+    .where(
+      and(
+        inArray(schema.crmConnections.id, [
+          ...new Set(connectedRecords.map((record) => record.connectionId)),
+        ]),
+        accessFilter(schema.crmConnections, schema.crmConnectionShares),
+      ),
+    );
+  const connectionById = new Map(
+    connections.map((connection) => [connection.id, connection]),
+  );
+  // One workspace lookup per connection, not per record.
+  const contextByConnectionId = new Map<string, ConnectionLinkContext>();
+  for (const record of connectedRecords) {
+    const connection = connectionById.get(record.connectionId);
+    if (!connection) continue;
+    const provider = record.provider as ConnectedCrmProvider;
+    let context = contextByConnectionId.get(record.connectionId);
+    if (!context) {
+      context = await connectionLinkContext({
+        provider,
+        accountId: connection.accountId,
+        workspaceConnectionId: connection.workspaceConnectionId,
+      });
+      contextByConnectionId.set(record.connectionId, context);
+    }
+    links.set(record.id, linkFromContext(context, { ...record, provider }));
+  }
+  return links;
+}

package/corpus/templates/crm/server/crm/read-through.ts

@@ -0,0 +1,207 @@
+import type {
+  CrmAccessScope,
+  CrmAdapter,
+  CrmFieldStoragePolicy,
+  CrmObjectKind,
+  CrmRecord,
+  CrmRelationship,
+} from "../../shared/crm-contract.js";
+
+export const MAX_READ_THROUGH_RELATIONSHIPS = 100;
+
+export type ReadThroughFieldPolicy = {
+  fieldName: string;
+  storagePolicy: CrmFieldStoragePolicy;
+  readable: boolean;
+  sensitive: boolean;
+};
+
+export type RelatedRecordSummary = {
+  id: string;
+  displayName: string;
+  kind: string;
+  relationshipType: string;
+  relationshipLabel?: string;
+  subtitle?: string;
+};
+
+export type ReadThroughRecordContext = {
+  id: string;
+  objectType: string;
+  kind: CrmObjectKind;
+  remoteId: string;
+  accessScopeJson: string;
+  fieldPolicies: ReadThroughFieldPolicy[];
+};
+
+export type VerifiedReadThroughRecord = {
+  remote: CrmRecord;
+  currentScope: CrmAccessScope;
+  relationships: CrmRelationship[];
+  currentScopes: Map<string, CrmAccessScope>;
+};
+
+type ReadThroughAdapter = CrmAdapter & {
+  getAccessScope(objectType: string): CrmAccessScope | Promise<CrmAccessScope>;
+};
+
+export function parseCrmAccessScope(value: string): CrmAccessScope | null {
+  try {
+    const scope = JSON.parse(value) as Partial<CrmAccessScope>;
+    if (
+      !scope ||
+      typeof scope.key !== "string" ||
+      !scope.key ||
+      (scope.mode !== "user" &&
+        scope.mode !== "service-account" &&
+        scope.mode !== "native") ||
+      typeof scope.objectReadable !== "boolean" ||
+      (scope.recordVisibility !== "actor" &&
+        scope.recordVisibility !== "cohort" &&
+        scope.recordVisibility !== "workspace" &&
+        scope.recordVisibility !== "unknown")
+    ) {
+      return null;
+    }
+    return scope as CrmAccessScope;
+  } catch {
+    return null;
+  }
+}
+
+export function scopesAreCompatible(
+  stored: CrmAccessScope | null,
+  current: CrmAccessScope,
+): boolean {
+  if (!stored || !stored.objectReadable || !current.objectReadable)
+    return false;
+  return (
+    stored.key === current.key &&
+    stored.mode === current.mode &&
+    stored.actorId === current.actorId &&
+    stored.grantId === current.grantId &&
+    stored.recordVisibility === current.recordVisibility &&
+    stored.fieldPermissionsHash === current.fieldPermissionsHash &&
+    stored.sharingFingerprint === current.sharingFingerprint
+  );
+}
+
+export function readThroughFieldNames(
+  policies: ReadThroughFieldPolicy[],
+): string[] {
+  return policies
+    .filter(
+      (policy) =>
+        policy.readable &&
+        !policy.sensitive &&
+        policy.storagePolicy === "mirrored",
+    )
+    .map((policy) => policy.fieldName)
+    .slice(0, 80);
+}
+
+export async function loadVerifiedReadThroughRecord(input: {
+  adapter: ReadThroughAdapter;
+  context: ReadThroughRecordContext;
+}): Promise<VerifiedReadThroughRecord> {
+  const currentScope = await input.adapter.getAccessScope(
+    input.context.objectType,
+  );
+  const storedScope = parseCrmAccessScope(input.context.accessScopeJson);
+  if (!scopesAreCompatible(storedScope, currentScope)) {
+    throw new Error(
+      "CRM provider access changed; the local record is withheld until it is refreshed.",
+    );
+  }
+  const remote = await input.adapter.getRecord({
+    record: {
+      connectionId: input.adapter.connection.connectionId,
+      provider: input.adapter.connection.provider,
+      objectType: input.context.objectType,
+      kind: input.context.kind,
+      remoteId: input.context.remoteId,
+      localId: input.context.id,
+    },
+    fields: readThroughFieldNames(input.context.fieldPolicies),
+  });
+  if (!remote || !scopesAreCompatible(storedScope, remote.accessScope)) {
+    throw new Error(
+      "CRM provider access changed or the record is unavailable; the local record is withheld until it is refreshed.",
+    );
+  }
+  const relationshipPage = await input.adapter.listRelationships({
+    record: remote.ref,
+    limit: MAX_READ_THROUGH_RELATIONSHIPS,
+  });
+  const targetObjectTypes = Array.from(
+    new Set(
+      relationshipPage.relationships.map(
+        (relationship) => relationship.to.objectType,
+      ),
+    ),
+  ).slice(0, 20);
+  return {
+    remote,
+    currentScope,
+    relationships: relationshipPage.relationships,
+    currentScopes: new Map(
+      await Promise.all(
+        targetObjectTypes.map(
+          async (objectType) =>
+            [
+              objectType,
+              await input.adapter.getAccessScope(objectType),
+            ] as const,
+        ),
+      ),
+    ),
+  };
+}
+
+export function relatedSummaries<
+  T extends {
+    id: string;
+    remoteId: string;
+    objectType: string;
+    displayName: string;
+    kind: string;
+    primaryEmail: string | null;
+    domain: string | null;
+  },
+>(
+  sourceRemoteId: string,
+  relationships: CrmRelationship[],
+  localRecords: T[],
+): Array<RelatedRecordSummary & { localId: string; remoteId: string }> {
+  const recordsByIdentity = new Map(
+    localRecords.map((record) => [
+      `${record.objectType}:${record.remoteId}`,
+      record,
+    ]),
+  );
+  return relationships
+    .filter((relationship) => relationship.from.remoteId === sourceRemoteId)
+    .slice(0, MAX_READ_THROUGH_RELATIONSHIPS)
+    .flatMap((relationship) => {
+      const record = recordsByIdentity.get(
+        `${relationship.to.objectType}:${relationship.to.remoteId}`,
+      );
+      if (!record) return [];
+      return [
+        {
+          id: record.id,
+          localId: record.id,
+          remoteId: record.remoteId,
+          displayName: record.displayName,
+          kind: record.kind,
+          relationshipType: relationship.relationshipType,
+          ...(relationship.label
+            ? { relationshipLabel: relationship.label }
+            : {}),
+          ...((record.domain ?? record.primaryEmail)
+            ? { subtitle: record.domain ?? record.primaryEmail ?? undefined }
+            : {}),
+        },
+      ];
+    });
+}