@agent-native/core 0.123.0 → 0.123.1

package/corpus/templates/crm/server/crm/hubspot-adapter.ts

@@ -0,0 +1,1146 @@
+import {
+  resolveWorkspaceConnectionCredentialForApp,
+  resolveWorkspaceConnectionForApp,
+  type ResolvedWorkspaceConnectionForApp,
+  type WorkspaceConnectionForApp,
+} from "@agent-native/core/workspace-connections";
+
+import type {
+  CrmAccessScope,
+  CrmAdapter,
+  CrmAdapterCapabilities,
+  CrmConnectionRef,
+  CrmFieldDefinition,
+  CrmObjectDefinition,
+  CrmObjectKind,
+  CrmObjectRef,
+  CrmProvenance,
+  CrmRecord,
+  CrmRecordRef,
+  CrmRelationship,
+  CrmSyncPage,
+  CrmValue,
+} from "../../shared/crm-contract.js";
+
+const HUBSPOT_API_BASE = "https://api.hubapi.com";
+const CRM_APP_ID = "crm";
+const HUBSPOT_CREDENTIAL_KEYS = [
+  "HUBSPOT_ACCESS_TOKEN",
+  "HUBSPOT_PRIVATE_APP_TOKEN",
+] as const;
+const CORE_OBJECT_TYPES = ["companies", "contacts", "deals"] as const;
+const MAX_PAGE_SIZE = 100;
+const MAX_RETRY_ATTEMPTS = 3;
+const MAX_RETRY_DELAY_MS = 1_500;
+const MAX_SINGLE_RETRY_DELAY_MS = 1_000;
+const REQUEST_TIMEOUT_MS = 10_000;
+
+type HubSpotObjectType = (typeof CORE_OBJECT_TYPES)[number] | string;
+
+export interface HubSpotTransportRequest {
+  path: string;
+  method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+  body?: unknown;
+  headers?: Record<string, string>;
+  retrySafe?: boolean;
+}
+
+export interface HubSpotTransportResponse {
+  status: number;
+  body?: unknown;
+  headers?: Record<string, string | undefined>;
+}
+
+export interface HubSpotTransport {
+  request(input: HubSpotTransportRequest): Promise<HubSpotTransportResponse>;
+}
+
+export interface CreateHubSpotCrmAdapterOptions {
+  connectionId?: string;
+  userEmail?: string;
+  orgId?: string | null;
+  transport?: HubSpotTransport;
+}
+
+export interface HubSpotCrmAdapterOptions {
+  connection: WorkspaceConnectionForApp;
+  transport: HubSpotTransport;
+  accessScope?: CrmAccessScope;
+}
+
+type HubSpotProperty = {
+  name?: string;
+  label?: string;
+  type?: string;
+  fieldType?: string;
+  hidden?: boolean;
+  readOnlyValue?: boolean;
+  calculated?: boolean;
+  required?: boolean;
+  options?: Array<{ value?: string; label?: string; hidden?: boolean }>;
+  referencedObjectType?: string;
+  sensitiveDataCategory?: string;
+};
+
+type HubSpotSchema = {
+  objectTypeId?: string | number;
+  name?: string;
+  labels?: { singular?: string; plural?: string };
+  metaType?: string;
+  properties?: HubSpotProperty[];
+};
+
+type HubSpotRecord = {
+  id?: string | number;
+  properties?: Record<string, unknown>;
+  createdAt?: string;
+  updatedAt?: string;
+  archived?: boolean;
+};
+
+type HubSpotListResponse = {
+  results?: HubSpotRecord[];
+  paging?: { next?: { after?: string } };
+};
+
+type HubSpotAssociation = {
+  toObjectId?: string | number;
+  id?: string | number;
+  associationTypes?: Array<{
+    associationCategory?: string;
+    associationTypeId?: string | number;
+    label?: string | null;
+  }>;
+};
+
+type HubSpotAssociationResponse = {
+  results?: HubSpotAssociation[];
+  paging?: { next?: { after?: string } };
+};
+
+function nonEmpty(value: string | undefined | null): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed || undefined;
+}
+
+function uniqueStrings(values: readonly string[]): string[] {
+  return Array.from(
+    new Set(values.map((value) => value.trim()).filter(Boolean)),
+  );
+}
+
+function objectKind(objectType: string): CrmObjectKind {
+  switch (objectType.toLowerCase()) {
+    case "companies":
+      return "account";
+    case "contacts":
+      return "person";
+    case "deals":
+      return "opportunity";
+    case "tasks":
+      return "task";
+    case "calls":
+    case "emails":
+    case "meetings":
+    case "notes":
+      return "activity";
+    default:
+      return "custom";
+  }
+}
+
+function objectDisplayProperty(objectType: string): string[] {
+  switch (objectType.toLowerCase()) {
+    case "companies":
+      return ["name", "domain"];
+    case "contacts":
+      return ["firstname", "lastname", "email"];
+    case "deals":
+      return ["dealname"];
+    case "tickets":
+      return ["subject"];
+    default:
+      return ["name", "hs_object_id"];
+  }
+}
+
+function propertyValueType(
+  property: HubSpotProperty,
+): CrmFieldDefinition["valueType"] {
+  const type = property.type?.toLowerCase();
+  const fieldType = property.fieldType?.toLowerCase();
+  if (fieldType === "checkbox") return "multi-enum";
+  if (type === "enumeration") return "enum";
+  if (type === "bool" || type === "boolean") return "boolean";
+  if (type === "number") return "number";
+  if (type === "date") return "date";
+  if (type === "datetime") return "datetime";
+  if (type === "json") return "json";
+  if (fieldType === "currency" || property.name === "amount") return "currency";
+  if (fieldType === "percentage") return "percent";
+  if (type === "object_coordinates" || type === "reference") return "reference";
+  return "string";
+}
+
+function propertyIsSensitive(property: HubSpotProperty): boolean {
+  const category = property.sensitiveDataCategory?.trim().toLowerCase();
+  return Boolean(
+    category && category !== "none" && category !== "not_sensitive",
+  );
+}
+
+function scalarValue(value: unknown): CrmValue | undefined {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    const values = value.filter(
+      (item): item is string | number | boolean | null =>
+        item === null ||
+        typeof item === "string" ||
+        typeof item === "number" ||
+        typeof item === "boolean",
+    );
+    return values.length === value.length ? values : undefined;
+  }
+  return undefined;
+}
+
+function toQuery(params: Record<string, string | undefined>): string {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value) query.set(key, value);
+  }
+  const value = query.toString();
+  return value ? `?${value}` : "";
+}
+
+function encodeCursorState(value: { index: number; after?: string }): string {
+  const bytes = new TextEncoder().encode(JSON.stringify(value));
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary)
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+function decodedCursor(cursor: string | undefined): {
+  index: number;
+  after?: string;
+} {
+  if (!cursor) return { index: 0 };
+  try {
+    const padded = cursor
+      .replace(/-/g, "+")
+      .replace(/_/g, "/")
+      .padEnd(Math.ceil(cursor.length / 4) * 4, "=");
+    const binary = atob(padded);
+    const decoded = JSON.parse(
+      new TextDecoder().decode(
+        Uint8Array.from(binary, (character) => character.charCodeAt(0)),
+      ),
+    ) as { index?: unknown; after?: unknown };
+    const index = typeof decoded.index === "number" ? decoded.index : 0;
+    return {
+      index: Number.isInteger(index) && index >= 0 ? index : 0,
+      ...(typeof decoded.after === "string" && decoded.after
+        ? { after: decoded.after }
+        : {}),
+    };
+  } catch {
+    // HubSpot's `after` values are already opaque; accept them for one-object callers.
+    return { index: 0, after: cursor };
+  }
+}
+
+function encodedCursor(index: number, after?: string): string | undefined {
+  if (!after) return undefined;
+  return encodeCursorState({ index, after });
+}
+
+function scopeAllows(
+  connection: WorkspaceConnectionForApp,
+  objectType: string,
+  operation: "read" | "write",
+): boolean {
+  const scopes = [
+    ...connection.scopes,
+    ...(connection.explicitGrant?.scopes ?? []),
+  ].map((scope) => scope.toLowerCase());
+  if (scopes.length === 0) return operation === "read";
+  const singular = objectType.toLowerCase().replace(/s$/, "");
+  return scopes.some(
+    (scope) =>
+      scope === "all" ||
+      scope === "crm" ||
+      scope === `crm.${operation}` ||
+      scope === `crm.objects.${operation}` ||
+      scope === `crm.objects.${objectType.toLowerCase()}.${operation}` ||
+      scope === `crm.objects.${singular}.${operation}` ||
+      (operation === "write" && scope.endsWith(".write")),
+  );
+}
+
+function accessScopeFor(
+  connection: WorkspaceConnectionForApp,
+  objectType: string,
+): CrmAccessScope {
+  const grantId = connection.appAccess.grantId ?? undefined;
+  const mode = [
+    ...connection.credentialRefs,
+    ...(connection.explicitGrant?.credentialRefs ?? []),
+  ].some((ref) => ref.scope === "user")
+    ? "user"
+    : "service-account";
+  const readable = scopeAllows(connection, objectType, "read");
+  const writable = scopeAllows(connection, objectType, "write");
+  return {
+    key: `${connection.id}:${grantId ?? connection.appAccess.mode}`,
+    actorId: connection.ownerEmail,
+    grantId,
+    mode,
+    objectReadable: readable,
+    objectCreateable: writable,
+    objectUpdateable: writable,
+    objectDeleteable: false,
+    recordVisibility: mode === "user" ? "actor" : "unknown",
+  };
+}
+
+function definitionFrom(
+  connection: WorkspaceConnectionForApp,
+  objectType: string,
+  schema: HubSpotSchema | undefined,
+  properties: HubSpotProperty[],
+): CrmObjectDefinition {
+  const scope = accessScopeFor(connection, objectType);
+  const custom =
+    !CORE_OBJECT_TYPES.includes(
+      objectType as (typeof CORE_OBJECT_TYPES)[number],
+    ) && schema?.metaType !== "HUBSPOT";
+  return {
+    connectionId: connection.id,
+    provider: "hubspot",
+    ...(connection.accountId ? { accountId: connection.accountId } : {}),
+    actorId: connection.ownerEmail,
+    objectType,
+    kind: objectKind(objectType),
+    label: schema?.labels?.singular || objectType,
+    pluralLabel: schema?.labels?.plural || objectType,
+    custom,
+    queryable: scope.objectReadable,
+    searchable: scope.objectReadable,
+    createable: scope.objectCreateable,
+    updateable: scope.objectUpdateable,
+    deleteable: false,
+    fields: properties
+      .map((property): CrmFieldDefinition | null => {
+        const name = nonEmpty(property.name);
+        if (!name) return null;
+        const sensitive = propertyIsSensitive(property);
+        return {
+          name,
+          label: property.label || name,
+          valueType: propertyValueType(property),
+          storagePolicy: sensitive ? "redacted" : "remote-only",
+          sensitive,
+          readable: !property.hidden && scope.objectReadable,
+          createable:
+            !sensitive &&
+            !property.readOnlyValue &&
+            !property.calculated &&
+            scope.objectCreateable,
+          updateable:
+            !sensitive &&
+            !property.readOnlyValue &&
+            !property.calculated &&
+            scope.objectUpdateable,
+          required: property.required === true,
+          ...(property.options
+            ? {
+                options: property.options
+                  .filter((option) => nonEmpty(option.value))
+                  .map((option) => ({
+                    value: option.value!.trim(),
+                    label: option.label || option.value!.trim(),
+                    ...(option.hidden ? { active: false } : {}),
+                  })),
+              }
+            : {}),
+          ...(property.referencedObjectType
+            ? { referencedObjectType: property.referencedObjectType }
+            : {}),
+        };
+      })
+      .filter((field): field is CrmFieldDefinition => field !== null),
+  };
+}
+
+function recordRef(
+  connection: WorkspaceConnectionForApp,
+  objectType: string,
+  remoteId: string,
+): CrmRecordRef {
+  return {
+    connectionId: connection.id,
+    provider: "hubspot",
+    ...(connection.accountId ? { accountId: connection.accountId } : {}),
+    actorId: connection.ownerEmail,
+    objectType,
+    kind: objectKind(objectType),
+    remoteId,
+  };
+}
+
+function provenance(
+  connection: WorkspaceConnectionForApp,
+  objectType: string,
+  remoteId: string,
+  remoteRevision: string | undefined,
+  fieldNames: string[],
+): CrmProvenance[] {
+  const observedAt = new Date().toISOString();
+  return fieldNames.map((fieldName) => ({
+    provider: "hubspot",
+    connectionId: connection.id,
+    objectType,
+    remoteId,
+    fieldName,
+    ...(remoteRevision ? { remoteRevision } : {}),
+    observedAt,
+  }));
+}
+
+function projectRecord(
+  connection: WorkspaceConnectionForApp,
+  objectType: string,
+  source: HubSpotRecord,
+  fieldAllowList: string[],
+): CrmRecord | null {
+  const remoteId = source.id == null ? undefined : String(source.id);
+  if (!remoteId) return null;
+  const allowed = uniqueStrings(fieldAllowList);
+  const fields: Record<string, CrmValue> = {};
+  for (const fieldName of allowed) {
+    const value = scalarValue(source.properties?.[fieldName]);
+    if (value !== undefined) fields[fieldName] = value;
+  }
+  const displayValues = objectDisplayProperty(objectType)
+    .map((fieldName) => fields[fieldName])
+    .filter((value): value is CrmValue => value !== undefined)
+    .filter(
+      (value): value is string | number | boolean =>
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean",
+    );
+  const displayName =
+    displayValues.map(String).filter(Boolean).join(" ") || remoteId;
+  const remoteRevision = source.updatedAt;
+  return {
+    ref: recordRef(connection, objectType, remoteId),
+    displayName,
+    fields,
+    ...(remoteRevision ? { remoteRevision } : {}),
+    ...(source.updatedAt ? { remoteUpdatedAt: source.updatedAt } : {}),
+    deleted: source.archived === true,
+    accessScope: accessScopeFor(connection, objectType),
+    provenance: provenance(
+      connection,
+      objectType,
+      remoteId,
+      remoteRevision,
+      Object.keys(fields),
+    ),
+  };
+}
+
+function isNotFound(error: unknown): boolean {
+  return error instanceof HubSpotApiError && error.status === 404;
+}
+
+class HubSpotApiError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+function hubSpotErrorMessage(status: number): string {
+  if (status === 401 || status === 403)
+    return "HubSpot authentication or authorization failed.";
+  if (status === 404) return "HubSpot resource was not found.";
+  if (status === 429) return "HubSpot rate limit exceeded.";
+  if (status >= 500) return "HubSpot service is temporarily unavailable.";
+  return "HubSpot request failed.";
+}
+
+function headerValue(
+  headers: Record<string, string | undefined> | undefined,
+  name: string,
+): string | undefined {
+  if (!headers) return undefined;
+  const expected = name.toLowerCase();
+  return Object.entries(headers).find(
+    ([key]) => key.toLowerCase() === expected,
+  )?.[1];
+}
+
+export function hubSpotRetryDelayMs(
+  response: HubSpotTransportResponse,
+  attempt: number,
+  elapsedMs: number,
+  now = Date.now(),
+): number {
+  const retryAfter = headerValue(response.headers, "retry-after")?.trim();
+  const numericRetryAfter = retryAfter ? Number(retryAfter) : Number.NaN;
+  const requestedDelay = Number.isFinite(numericRetryAfter)
+    ? Math.max(0, numericRetryAfter * 1_000)
+    : retryAfter
+      ? Math.max(0, Date.parse(retryAfter) - now)
+      : 100 * 2 ** attempt;
+  return Math.max(
+    0,
+    Math.min(
+      requestedDelay,
+      MAX_SINGLE_RETRY_DELAY_MS,
+      MAX_RETRY_DELAY_MS - elapsedMs,
+    ),
+  );
+}
+
+function canRetryHubSpotResponse(status: number): boolean {
+  return status === 429 || status >= 500;
+}
+
+function assertOwnedRecord(
+  connection: WorkspaceConnectionForApp,
+  record: CrmRecordRef,
+): void {
+  if (record.provider !== "hubspot" || record.connectionId !== connection.id) {
+    throw new Error(
+      "HubSpot record does not belong to this workspace connection.",
+    );
+  }
+}
+
+class FetchHubSpotTransport implements HubSpotTransport {
+  constructor(private readonly token: string) {}
+
+  async request(
+    input: HubSpotTransportRequest,
+  ): Promise<HubSpotTransportResponse> {
+    const response = await fetch(`${HUBSPOT_API_BASE}${input.path}`, {
+      method: input.method ?? "GET",
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        ...(input.body === undefined
+          ? {}
+          : { "Content-Type": "application/json" }),
+        ...input.headers,
+      },
+      ...(input.body === undefined ? {} : { body: JSON.stringify(input.body) }),
+    });
+    const text = await response.text();
+    let body: unknown;
+    if (text) {
+      try {
+        body = JSON.parse(text);
+      } catch {
+        body = text;
+      }
+    }
+    return {
+      status: response.status,
+      body,
+      headers: {
+        "retry-after": response.headers.get("retry-after") ?? undefined,
+      },
+    };
+  }
+}
+
+export class HubSpotCrmAdapter implements CrmAdapter {
+  readonly connection: CrmConnectionRef;
+  readonly capabilities: CrmAdapterCapabilities = {
+    schemaDiscovery: true,
+    customObjects: true,
+    search: true,
+    incrementalSync: true,
+    deletedRecordSync: true,
+    conditionalMutations: false,
+    labeledRelationships: true,
+    perFieldPermissions: false,
+    perRecordPermissions: false,
+  };
+
+  private readonly workspaceConnection: WorkspaceConnectionForApp;
+  private readonly transport: HubSpotTransport;
+
+  constructor(options: HubSpotCrmAdapterOptions) {
+    this.workspaceConnection = options.connection;
+    this.transport = options.transport;
+    this.connection = {
+      connectionId: options.connection.id,
+      provider: "hubspot",
+      ...(options.connection.accountId
+        ? { accountId: options.connection.accountId }
+        : {}),
+      actorId: options.connection.ownerEmail,
+    };
+  }
+
+  private async request<T>(input: HubSpotTransportRequest): Promise<T> {
+    const readRetrySafe =
+      input.retrySafe === true ||
+      input.method === undefined ||
+      input.method === "GET";
+    let elapsedDelayMs = 0;
+    for (let attempt = 0; attempt < MAX_RETRY_ATTEMPTS; attempt++) {
+      const response = await this.transport.request(input);
+      if (response.status >= 200 && response.status < 300) {
+        return (response.body ?? {}) as T;
+      }
+      const mayRetry =
+        attempt + 1 < MAX_RETRY_ATTEMPTS &&
+        readRetrySafe &&
+        canRetryHubSpotResponse(response.status) &&
+        elapsedDelayMs < MAX_RETRY_DELAY_MS;
+      if (!mayRetry) {
+        throw new HubSpotApiError(
+          response.status,
+          `HubSpot API error ${response.status}: ${hubSpotErrorMessage(response.status)}`,
+        );
+      }
+      const delay = hubSpotRetryDelayMs(response, attempt, elapsedDelayMs);
+      if (delay <= 0) {
+        continue;
+      }
+      await new Promise<void>((resolve) => setTimeout(resolve, delay));
+      elapsedDelayMs += delay;
+    }
+    throw new Error("HubSpot retry budget was exhausted.");
+  }
+
+  private async schema(objectType: string): Promise<HubSpotSchema | undefined> {
+    try {
+      return await this.request<HubSpotSchema>({
+        path: `/crm/v3/schemas/${encodeURIComponent(objectType)}`,
+      });
+    } catch (error) {
+      if (isNotFound(error)) return undefined;
+      throw error;
+    }
+  }
+
+  private async properties(objectType: string): Promise<HubSpotProperty[]> {
+    const response = await this.request<{ results?: HubSpotProperty[] }>({
+      path: `/crm/v3/properties/${encodeURIComponent(objectType)}`,
+    });
+    return response.results ?? [];
+  }
+
+  private async objectDefinition(
+    objectType: string,
+  ): Promise<CrmObjectDefinition> {
+    const [schema, properties] = await Promise.all([
+      this.schema(objectType),
+      this.properties(objectType),
+    ]);
+    return definitionFrom(
+      this.workspaceConnection,
+      objectType,
+      schema,
+      properties,
+    );
+  }
+
+  async discoverObjects(): Promise<CrmObjectDefinition[]> {
+    const schemas = await this.request<{ results?: HubSpotSchema[] }>({
+      path: "/crm/v3/schemas",
+    });
+    const objectTypes = uniqueStrings([
+      ...CORE_OBJECT_TYPES,
+      ...(schemas.results ?? []).map(
+        (schema) =>
+          nonEmpty(schema.name) ??
+          (schema.objectTypeId == null ? "" : String(schema.objectTypeId)),
+      ),
+    ]);
+    return Promise.all(
+      objectTypes.map((objectType) => this.objectDefinition(objectType)),
+    );
+  }
+
+  async describeObject(objectType: string): Promise<CrmObjectDefinition> {
+    const normalized = nonEmpty(objectType);
+    if (!normalized) throw new Error("HubSpot objectType is required.");
+    return this.objectDefinition(normalized);
+  }
+
+  getAccessScope(objectType: string): CrmAccessScope {
+    const normalized = nonEmpty(objectType);
+    if (!normalized) throw new Error("HubSpot objectType is required.");
+    return accessScopeFor(this.workspaceConnection, normalized);
+  }
+
+  private async listPage(input: {
+    objectType: HubSpotObjectType;
+    fields: string[];
+    limit: number;
+    cursor?: string;
+    archived?: boolean;
+    filterGroups?: unknown[];
+  }): Promise<HubSpotListResponse> {
+    const objectType = encodeURIComponent(input.objectType);
+    if (input.filterGroups?.length) {
+      return this.request<HubSpotListResponse>({
+        method: "POST",
+        retrySafe: true,
+        path: `/crm/v3/objects/${objectType}/search`,
+        body: {
+          limit: input.limit,
+          ...(input.cursor ? { after: input.cursor } : {}),
+          ...(input.fields.length ? { properties: input.fields } : {}),
+          filterGroups: input.filterGroups,
+        },
+      });
+    }
+    return this.request<HubSpotListResponse>({
+      path: `/crm/v3/objects/${objectType}${toQuery({
+        limit: String(input.limit),
+        ...(input.cursor ? { after: input.cursor } : {}),
+        ...(input.fields.length ? { properties: input.fields.join(",") } : {}),
+        ...(input.archived ? { archived: "true" } : {}),
+      })}`,
+    });
+  }
+
+  private filtersForScope(scope: {
+    objectType: string;
+    pipelineIds?: string[];
+    ownerIds?: string[];
+    updatedAfter?: string;
+  }): unknown[] {
+    const filters: Array<Record<string, unknown>> = [];
+    if (
+      scope.objectType.toLowerCase() === "deals" &&
+      scope.pipelineIds?.length
+    ) {
+      filters.push({
+        propertyName: "pipeline",
+        operator: "IN",
+        values: uniqueStrings(scope.pipelineIds),
+      });
+    }
+    if (scope.ownerIds?.length) {
+      filters.push({
+        propertyName: "hubspot_owner_id",
+        operator: "IN",
+        values: uniqueStrings(scope.ownerIds),
+      });
+    }
+    if (scope.updatedAfter) {
+      filters.push({
+        propertyName:
+          scope.objectType.toLowerCase() === "contacts"
+            ? "lastmodifieddate"
+            : "hs_lastmodifieddate",
+        operator: "GTE",
+        value: scope.updatedAfter,
+      });
+    }
+    return filters.length ? [{ filters }] : [];
+  }
+
+  async syncPage(input: {
+    scope: {
+      objectType: string;
+      pipelineIds?: string[];
+      ownerIds?: string[];
+      recordIds?: string[];
+      associatedRecordIds?: string[];
+      updatedAfter?: string;
+      includeDeleted?: boolean;
+    };
+    fieldAllowList: string[];
+    cursor?: string;
+    limit: number;
+  }): Promise<CrmSyncPage> {
+    const objectType = nonEmpty(input.scope.objectType);
+    if (!objectType)
+      throw new Error("HubSpot sync scope objectType is required.");
+    const fields = uniqueStrings(input.fieldAllowList);
+    const limit = Math.max(1, Math.min(MAX_PAGE_SIZE, input.limit));
+    const recordIds = uniqueStrings(input.scope.recordIds ?? []);
+    let page: HubSpotListResponse;
+    if (recordIds.length) {
+      const state = decodedCursor(input.cursor);
+      const offset = Math.min(state.index, recordIds.length);
+      page = await this.request<HubSpotListResponse>({
+        method: "POST",
+        retrySafe: true,
+        path: `/crm/v3/objects/${encodeURIComponent(objectType)}/batch/read`,
+        body: {
+          inputs: recordIds.slice(offset, offset + limit).map((id) => ({ id })),
+          ...(fields.length ? { properties: fields } : {}),
+          ...(input.scope.includeDeleted ? { archived: true } : {}),
+        },
+      });
+    } else {
+      page = await this.listPage({
+        objectType,
+        fields,
+        limit,
+        cursor: input.cursor,
+        archived: input.scope.includeDeleted,
+        filterGroups: this.filtersForScope(input.scope),
+      });
+    }
+    const associatedIds = new Set(
+      uniqueStrings(input.scope.associatedRecordIds ?? []),
+    );
+    const records = (page.results ?? [])
+      .filter(
+        (record) => !associatedIds.size || associatedIds.has(String(record.id)),
+      )
+      .map((record) =>
+        projectRecord(this.workspaceConnection, objectType, record, fields),
+      )
+      .filter((record): record is CrmRecord => record !== null);
+    const nextCursor = recordIds.length
+      ? (() => {
+          const offset = decodedCursor(input.cursor).index + limit;
+          return offset < recordIds.length
+            ? encodeCursorState({ index: offset })
+            : undefined;
+        })()
+      : page.paging?.next?.after;
+    return {
+      records,
+      relationships: [],
+      ...(nextCursor ? { nextCursor } : {}),
+      complete: !nextCursor,
+    };
+  }
+
+  async getRecord(input: {
+    record: CrmRecordRef;
+    fields: string[];
+  }): Promise<CrmRecord | null> {
+    assertOwnedRecord(this.workspaceConnection, input.record);
+    const fields = uniqueStrings(input.fields);
+    try {
+      const record = await this.request<HubSpotRecord>({
+        path: `/crm/v3/objects/${encodeURIComponent(input.record.objectType)}/${encodeURIComponent(input.record.remoteId)}${toQuery(
+          {
+            ...(fields.length ? { properties: fields.join(",") } : {}),
+          },
+        )}`,
+      });
+      return projectRecord(
+        this.workspaceConnection,
+        input.record.objectType,
+        record,
+        fields,
+      );
+    } catch (error) {
+      if (isNotFound(error)) return null;
+      throw error;
+    }
+  }
+
+  async search(input: {
+    objectTypes: string[];
+    query: string;
+    fields: string[];
+    limit: number;
+    cursor?: string;
+  }): Promise<CrmSyncPage> {
+    const objectTypes = uniqueStrings(input.objectTypes);
+    if (!objectTypes.length)
+      return { records: [], relationships: [], complete: true };
+    const fields = uniqueStrings(input.fields);
+    const limit = Math.max(1, Math.min(MAX_PAGE_SIZE, input.limit));
+    const state = decodedCursor(input.cursor);
+    const index = Math.min(state.index, objectTypes.length - 1);
+    const objectType = objectTypes[index]!;
+    const page = await this.request<HubSpotListResponse>({
+      method: "POST",
+      path: `/crm/v3/objects/${encodeURIComponent(objectType)}/search`,
+      body: {
+        query: input.query,
+        limit,
+        ...(state.after ? { after: state.after } : {}),
+        ...(fields.length ? { properties: fields } : {}),
+      },
+    });
+    const records = (page.results ?? [])
+      .map((record) =>
+        projectRecord(this.workspaceConnection, objectType, record, fields),
+      )
+      .filter((record): record is CrmRecord => record !== null);
+    const after = page.paging?.next?.after;
+    const nextCursor = after
+      ? encodedCursor(index, after)
+      : index + 1 < objectTypes.length
+        ? encodeCursorState({ index: index + 1 })
+        : undefined;
+    return {
+      records,
+      relationships: [],
+      ...(nextCursor ? { nextCursor } : {}),
+      complete: !nextCursor,
+    };
+  }
+
+  async listRelationships(input: {
+    record: CrmRecordRef;
+    targetObjectTypes?: string[];
+    limit: number;
+    cursor?: string;
+  }): Promise<{
+    relationships: CrmRelationship[];
+    nextCursor?: string;
+    complete: boolean;
+  }> {
+    assertOwnedRecord(this.workspaceConnection, input.record);
+    const targetObjectTypes = uniqueStrings(
+      input.targetObjectTypes?.length
+        ? input.targetObjectTypes
+        : CORE_OBJECT_TYPES,
+    ).filter((objectType) => objectType !== input.record.objectType);
+    if (!targetObjectTypes.length) {
+      return { relationships: [], complete: true };
+    }
+    const state = decodedCursor(input.cursor);
+    const index = Math.min(state.index, targetObjectTypes.length - 1);
+    const targetObjectType = targetObjectTypes[index]!;
+    const response = await this.request<HubSpotAssociationResponse>({
+      path: `/crm/v4/objects/${encodeURIComponent(input.record.objectType)}/${encodeURIComponent(input.record.remoteId)}/associations/${encodeURIComponent(targetObjectType)}${toQuery(
+        {
+          limit: String(Math.max(1, Math.min(MAX_PAGE_SIZE, input.limit))),
+          ...(state.after ? { after: state.after } : {}),
+        },
+      )}`,
+    });
+    const relationships: CrmRelationship[] = [];
+    for (const association of response.results ?? []) {
+      const remoteId = association.toObjectId ?? association.id;
+      if (remoteId == null) continue;
+      const types = association.associationTypes?.length
+        ? association.associationTypes
+        : [
+            {
+              associationCategory: "HUBSPOT_DEFINED",
+              associationTypeId: "default",
+            },
+          ];
+      for (const type of types) {
+        const relationshipType = [
+          type.associationCategory ?? "HUBSPOT_DEFINED",
+          type.associationTypeId == null
+            ? "default"
+            : String(type.associationTypeId),
+        ].join(":");
+        relationships.push({
+          from: input.record,
+          to: recordRef(
+            this.workspaceConnection,
+            targetObjectType,
+            String(remoteId),
+          ),
+          relationshipType,
+          ...(type.label ? { label: type.label } : {}),
+        });
+      }
+    }
+    const after = response.paging?.next?.after;
+    const nextCursor = after
+      ? encodedCursor(index, after)
+      : index + 1 < targetObjectTypes.length
+        ? encodeCursorState({ index: index + 1 })
+        : undefined;
+    return {
+      relationships,
+      ...(nextCursor ? { nextCursor } : {}),
+      complete: !nextCursor,
+    };
+  }
+
+  async applyMutation(mutation: Parameters<CrmAdapter["applyMutation"]>[0]) {
+    assertOwnedRecord(this.workspaceConnection, mutation.record);
+    if (!mutation.idempotencyKey.trim()) {
+      return {
+        status: "rejected" as const,
+        message: "An idempotency key is required.",
+      };
+    }
+    if (mutation.operation === "delete") {
+      return {
+        status: "rejected" as const,
+        message:
+          "HubSpot deletion is disabled during the phase-1 CRM transport rollout.",
+      };
+    }
+    if (
+      mutation.operation === "associate" ||
+      mutation.operation === "disassociate"
+    ) {
+      return {
+        status: "rejected" as const,
+        message:
+          "HubSpot association mutation requires an explicit association definition and is not enabled in phase 1.",
+      };
+    }
+    if (
+      !scopeAllows(
+        this.workspaceConnection,
+        mutation.record.objectType,
+        "write",
+      )
+    ) {
+      return {
+        status: "rejected" as const,
+        message:
+          "The workspace connection does not prove write access for this HubSpot object.",
+      };
+    }
+    const fields = Object.entries(mutation.fields ?? {}).reduce<
+      Record<string, CrmValue>
+    >((result, [key, value]) => {
+      if (key.trim()) result[key] = value;
+      return result;
+    }, {});
+    if (!Object.keys(fields).length) {
+      return {
+        status: "rejected" as const,
+        message: "At least one field is required.",
+      };
+    }
+    if (mutation.operation === "update" && !mutation.expectedRemoteRevision) {
+      return {
+        status: "rejected" as const,
+        message: "HubSpot updates require a current remote revision.",
+      };
+    }
+    if (mutation.expectedRemoteRevision) {
+      const current = await this.getRecord({
+        record: mutation.record,
+        fields: [],
+      });
+      if (
+        !current ||
+        current.remoteRevision !== mutation.expectedRemoteRevision
+      ) {
+        return {
+          status: "conflict" as const,
+          ...(current?.remoteRevision
+            ? { remoteRevision: current.remoteRevision }
+            : {}),
+          message:
+            "The HubSpot record changed before this mutation could be applied.",
+        };
+      }
+      if (!this.capabilities.conditionalMutations) {
+        return {
+          status: "rejected" as const,
+          remoteRevision: current.remoteRevision,
+          message:
+            "HubSpot does not support an atomic conditional update for this record.",
+        };
+      }
+    }
+    try {
+      const objectType = encodeURIComponent(mutation.record.objectType);
+      const response = await this.request<HubSpotRecord>({
+        method: mutation.operation === "create" ? "POST" : "PATCH",
+        path:
+          mutation.operation === "create"
+            ? `/crm/v3/objects/${objectType}`
+            : `/crm/v3/objects/${objectType}/${encodeURIComponent(mutation.record.remoteId)}`,
+        body: { properties: fields },
+        headers: { "X-Idempotency-Key": mutation.idempotencyKey },
+      });
+      const record = projectRecord(
+        this.workspaceConnection,
+        mutation.record.objectType,
+        response,
+        Object.keys(fields),
+      );
+      if (!record) {
+        return {
+          status: "rejected" as const,
+          message: "HubSpot returned no record identity.",
+        };
+      }
+      return {
+        status: "applied" as const,
+        record,
+        ...(record.remoteRevision
+          ? { remoteRevision: record.remoteRevision }
+          : {}),
+      };
+    } catch (error) {
+      return {
+        status: "rejected" as const,
+        message:
+          error instanceof Error ? error.message : "HubSpot mutation failed.",
+      };
+    }
+  }
+}
+
+function requireResolvedConnection(
+  result: ResolvedWorkspaceConnectionForApp,
+): WorkspaceConnectionForApp {
+  if (!result.available || !result.connection) {
+    throw new Error(
+      `HubSpot workspace connection is unavailable: ${result.reason}`,
+    );
+  }
+  return result.connection;
+}
+
+export async function createHubSpotCrmAdapter(
+  options: CreateHubSpotCrmAdapterOptions = {},
+): Promise<HubSpotCrmAdapter> {
+  const resolved = await resolveWorkspaceConnectionForApp({
+    appId: CRM_APP_ID,
+    provider: "hubspot",
+    ...(options.connectionId ? { connectionId: options.connectionId } : {}),
+    requireConnected: true,
+  });
+  const connection = requireResolvedConnection(resolved);
+  if (options.transport) {
+    return new HubSpotCrmAdapter({ connection, transport: options.transport });
+  }
+  for (const key of HUBSPOT_CREDENTIAL_KEYS) {
+    const credential = await resolveWorkspaceConnectionCredentialForApp({
+      appId: CRM_APP_ID,
+      provider: "hubspot",
+      key,
+      connectionId: connection.id,
+      ...(options.userEmail ? { userEmail: options.userEmail } : {}),
+      ...(options.orgId !== undefined ? { orgId: options.orgId } : {}),
+    });
+    if (!credential.available || !credential.value) continue;
+    if (credential.provenance?.connectionId !== connection.id) continue;
+    return new HubSpotCrmAdapter({
+      connection,
+      transport: new FetchHubSpotTransport(credential.value),
+    });
+  }
+  throw new Error(
+    "HubSpot workspace connection is unavailable: no scoped credential was resolved for the granted connection.",
+  );
+}