@agent-native/core 0.123.0 → 0.123.1

package/corpus/templates/crm/actions/save-crm-saved-view.ts

@@ -0,0 +1,296 @@
+import { defineAction, type ActionRunContext } from "@agent-native/core/action";
+import { accessFilter, assertAccess } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import {
+  CrmFilterError,
+  crmFilterSchema,
+  crmSortSchema,
+  hydrateSavedViewRow,
+  normalizeStoredColumns,
+  normalizeStoredFilter,
+} from "../server/lib/crm-query.js";
+import { requireCrmScope, toJson } from "./_crm-action-utils.js";
+
+/** A save that lost a race — surfaces as HTTP 409 instead of clobbering. */
+class CrmSavedViewConflictError extends Error {
+  readonly statusCode = 409;
+  readonly code = "crm-saved-view-conflict";
+
+  constructor(id: string, expected: string, actual: string) {
+    super(
+      `CRM saved view "${id}" changed between read and write (expected ${expected}, found ${actual}). Re-read it and re-apply your edit.`,
+    );
+    this.name = "CrmSavedViewConflictError";
+  }
+}
+
+const columnsSchema = z
+  .array(
+    z.union([
+      z.string().trim().min(1).max(128),
+      z.object({
+        attributeId: z.string().trim().min(1).max(128),
+        width: z.number().int().min(40).max(1_200).optional(),
+        hidden: z.boolean().optional(),
+      }),
+    ]),
+  )
+  .max(60);
+
+export default defineAction({
+  description:
+    "Create or update a bounded, access-scoped CRM saved view: its typed filter, ordered sort, columns, table/board presentation, and personal/shared audience. Pass expectedUpdatedAt to reject an overwrite when the view changed since it was read. A saved view stores filters and presentation settings, never provider rows.",
+  schema: z.object({
+    id: z.string().min(1).max(128).optional(),
+    name: z.string().trim().min(1).max(120),
+    description: z.string().trim().max(500).optional(),
+    /** Record kind (account/person/opportunity) — not the table/board kind. */
+    kind: z.enum(["account", "person", "opportunity"]).optional(),
+    viewKind: z.enum(["table", "board"]).optional(),
+    targetKind: z.enum(["object", "list"]).optional(),
+    targetId: z.string().trim().min(1).max(128).optional(),
+    groupByAttributeId: z
+      .string()
+      .trim()
+      .min(1)
+      .max(128)
+      .optional()
+      .describe("Board views only; must reference a status attribute."),
+    filter: crmFilterSchema.optional(),
+    /** Legacy `{query, fieldEquals}` blob; normalized into `filter`. */
+    filters: z.record(z.string().max(120), z.unknown()).optional(),
+    columns: columnsSchema.optional(),
+    sort: crmSortSchema.optional(),
+    dataProgramId: z.string().trim().min(1).max(128).optional(),
+    pinned: z.boolean().optional(),
+    audience: z.enum(["personal", "shared"]).optional(),
+    expectedUpdatedAt: z.string().min(1).max(64).optional(),
+  }),
+  audit: {
+    target: (_args, result) => {
+      const view = result as {
+        id: string;
+        ownerEmail: string;
+        orgId: string | null;
+        visibility: "private" | "org";
+      };
+      return {
+        type: "crm-saved-view",
+        id: view.id,
+        ownerEmail: view.ownerEmail,
+        orgId: view.orgId,
+        visibility: view.visibility,
+      };
+    },
+    summary: (args) => `Saved CRM view ${args.name}`,
+  },
+  run: async (args, ctx?: ActionRunContext) => {
+    if (args.filter && args.filters) {
+      throw new CrmFilterError(
+        "crm-filter-conflict",
+        "Pass either filter or the legacy filters blob, not both.",
+      );
+    }
+    const db = getDb();
+    const now = new Date().toISOString();
+    const scope = requireCrmScope(ctx);
+
+    const filter =
+      args.filter ??
+      (args.filters === undefined
+        ? undefined
+        : normalizeStoredFilter(args.filters));
+    const columns =
+      args.columns === undefined
+        ? undefined
+        : normalizeStoredColumns(args.columns);
+
+    const existing = args.id ? await readView(args.id) : undefined;
+    if (args.id && !existing) throw new Error("CRM saved view was not found.");
+
+    const viewKind = args.viewKind ?? existing?.viewKind ?? "table";
+    // Switching a board back to a table drops its grouping instead of
+    // inheriting it — otherwise the switch would fail the board-only check.
+    const groupByAttributeId =
+      args.groupByAttributeId !== undefined
+        ? args.groupByAttributeId
+        : viewKind === "board"
+          ? (existing?.groupByAttributeId ?? null)
+          : null;
+    if (viewKind === "board") {
+      if (!groupByAttributeId) {
+        throw new CrmFilterError(
+          "crm-saved-view-group-by",
+          "A board view needs groupByAttributeId naming a status attribute.",
+        );
+      }
+      await assertStatusAttribute(groupByAttributeId);
+    } else if (groupByAttributeId) {
+      throw new CrmFilterError(
+        "crm-saved-view-group-by",
+        "groupByAttributeId only applies to a board view.",
+      );
+    }
+
+    const visibility =
+      args.audience === undefined
+        ? undefined
+        : audienceVisibility(args.audience, scope.orgId);
+
+    if (args.id && existing) {
+      await assertAccess("crm-saved-view", args.id, "editor");
+      if (
+        args.expectedUpdatedAt !== undefined &&
+        args.expectedUpdatedAt !== existing.updatedAt
+      ) {
+        throw new CrmSavedViewConflictError(
+          args.id,
+          args.expectedUpdatedAt,
+          existing.updatedAt,
+        );
+      }
+      await db
+        .update(schema.crmSavedViews)
+        .set({
+          name: args.name,
+          ...(args.description !== undefined
+            ? { description: args.description }
+            : {}),
+          ...(args.kind !== undefined ? { kind: args.kind } : {}),
+          ...(args.viewKind !== undefined ? { viewKind } : {}),
+          ...(args.targetKind !== undefined
+            ? { targetKind: args.targetKind }
+            : {}),
+          ...(args.targetId !== undefined ? { targetId: args.targetId } : {}),
+          groupByAttributeId,
+          ...(filter !== undefined
+            ? { filtersJson: toJson(filter, 8_000) }
+            : {}),
+          ...(columns !== undefined
+            ? { columnsJson: toJson(columns, 8_000) }
+            : {}),
+          ...(args.sort !== undefined
+            ? { sortJson: toJson(args.sort, 2_000) }
+            : {}),
+          ...(args.dataProgramId !== undefined
+            ? { dataProgramId: args.dataProgramId }
+            : {}),
+          ...(args.pinned !== undefined ? { pinned: args.pinned } : {}),
+          ...(visibility !== undefined ? { visibility } : {}),
+          updatedAt: now,
+        })
+        .where(
+          and(
+            eq(schema.crmSavedViews.id, args.id),
+            ...(args.expectedUpdatedAt !== undefined
+              ? [eq(schema.crmSavedViews.updatedAt, args.expectedUpdatedAt)]
+              : []),
+          ),
+        );
+      const saved = await readView(args.id);
+      if (!saved) throw new Error("CRM saved view was not found.");
+      if (args.expectedUpdatedAt !== undefined && saved.updatedAt !== now) {
+        // The guarded UPDATE matched nothing: another writer landed between the
+        // read above and the write. Report it rather than returning the row we
+        // did not write as if the save succeeded.
+        throw new CrmSavedViewConflictError(
+          args.id,
+          args.expectedUpdatedAt,
+          saved.updatedAt,
+        );
+      }
+      return saved;
+    }
+
+    const id = crypto.randomUUID();
+    await db.insert(schema.crmSavedViews).values({
+      id,
+      name: args.name,
+      description: args.description ?? "",
+      kind: args.kind ?? null,
+      viewKind,
+      targetKind: args.targetKind ?? "object",
+      targetId: args.targetId ?? null,
+      groupByAttributeId,
+      filtersJson: toJson(filter ?? { op: "and", conditions: [] }, 8_000),
+      columnsJson: toJson(columns ?? [], 8_000),
+      sortJson: toJson(args.sort ?? [], 2_000),
+      dataProgramId: args.dataProgramId ?? null,
+      pinned: args.pinned ?? false,
+      ...scope,
+      ...(visibility !== undefined ? { visibility } : {}),
+      createdAt: now,
+      updatedAt: now,
+    });
+    const saved = await readView(id);
+    if (!saved)
+      throw new Error("CRM saved view could not be verified after saving.");
+    return saved;
+  },
+});
+
+function audienceVisibility(
+  audience: "personal" | "shared",
+  orgId: string | null,
+): "private" | "org" {
+  if (audience === "personal") return "private";
+  if (!orgId) {
+    throw new CrmFilterError(
+      "crm-saved-view-audience",
+      "A shared view needs an active organization; this session has none.",
+    );
+  }
+  return "org";
+}
+
+async function assertStatusAttribute(attributeId: string): Promise<void> {
+  const [row] = await getDb()
+    .select({
+      attributeType: schema.crmFieldPolicies.attributeType,
+      archived: schema.crmFieldPolicies.archived,
+    })
+    .from(schema.crmFieldPolicies)
+    .where(
+      and(
+        eq(schema.crmFieldPolicies.id, attributeId),
+        accessFilter(schema.crmFieldPolicies, schema.crmFieldPolicyShares),
+      ),
+    )
+    .limit(1);
+  if (!row) {
+    throw new CrmFilterError(
+      "crm-saved-view-group-by",
+      `Board grouping references unknown attribute "${attributeId}".`,
+    );
+  }
+  if (row.archived) {
+    throw new CrmFilterError(
+      "crm-saved-view-group-by",
+      `Board grouping references archived attribute "${attributeId}".`,
+    );
+  }
+  if (row.attributeType !== "status") {
+    throw new CrmFilterError(
+      "crm-saved-view-group-by",
+      `Board grouping needs a status attribute; "${attributeId}" is ${row.attributeType}.`,
+    );
+  }
+}
+
+async function readView(id: string) {
+  const [row] = await getDb()
+    .select()
+    .from(schema.crmSavedViews)
+    .where(
+      and(
+        eq(schema.crmSavedViews.id, id),
+        accessFilter(schema.crmSavedViews, schema.crmSavedViewShares),
+      ),
+    )
+    .limit(1);
+  if (!row) return undefined;
+  return { ...row, view: hydrateSavedViewRow(row) };
+}

package/corpus/templates/crm/actions/sync-crm.ts

@@ -0,0 +1,146 @@
+import { defineAction, type ActionRunContext } from "@agent-native/core/action";
+import { accessFilter, assertAccess } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import {
+  createConnectedCrmAdapter,
+  isConnectedCrmProvider,
+} from "../server/crm/adapter.js";
+import {
+  MAX_SYNC_PAGE_SIZE,
+  MAX_SYNC_PAGES,
+  syncCrmMirror,
+} from "../server/crm/crm-mirror.js";
+import { getDb, schema } from "../server/db/index.js";
+import { requireCrmScope } from "./_crm-action-utils.js";
+
+const idList = z
+  .array(z.string().trim().min(1).max(160))
+  .min(1)
+  .max(50)
+  .optional();
+const syncScopeSchema = z
+  .object({
+    pipelineIds: idList,
+    ownerIds: idList,
+    recordIds: idList,
+    associatedRecordIds: idList,
+    updatedAfter: z.string().datetime({ offset: true }).optional(),
+    includeDeleted: z.boolean().default(false),
+  })
+  .superRefine((scope, issue) => {
+    if (
+      !scope.pipelineIds &&
+      !scope.ownerIds &&
+      !scope.recordIds &&
+      !scope.associatedRecordIds &&
+      !scope.updatedAfter
+    ) {
+      issue.addIssue({
+        code: "custom",
+        message:
+          "A sync requires a bounded cohort selector: pipelineIds, ownerIds, recordIds, associatedRecordIds, or updatedAfter.",
+      });
+    }
+  });
+
+export default defineAction({
+  description:
+    "Thinly mirror one bounded HubSpot or Salesforce CRM object cohort. It discovers field policy first, mirrors only explicit safe fields, and returns a continuation cursor instead of claiming an exhaustive sync.",
+  schema: z.object({
+    connectionId: z.string().trim().min(1).max(128),
+    objectType: z.string().trim().min(1).max(120),
+    scope: syncScopeSchema,
+    fieldAllowList: z
+      .array(z.string().trim().min(1).max(120))
+      .min(1)
+      .max(80)
+      .optional(),
+    allowCustomObject: z.boolean().default(false),
+    cursor: z.string().trim().min(1).max(2_000).optional(),
+    pageSize: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(MAX_SYNC_PAGE_SIZE)
+      .default(MAX_SYNC_PAGE_SIZE),
+    maxPages: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(MAX_SYNC_PAGES)
+      .default(MAX_SYNC_PAGES),
+  }),
+  audit: {
+    target: (args, result) => {
+      const response = result as {
+        ownerEmail: string;
+        orgId: string | null;
+        visibility: "private" | "org";
+      };
+      return {
+        type: "crm-connection",
+        id: args.connectionId,
+        ownerEmail: response.ownerEmail,
+        orgId: response.orgId,
+        visibility: response.visibility,
+      };
+    },
+    summary: (args) => `Synced bounded CRM ${args.objectType} cohort`,
+    recordInputs: false,
+  },
+  run: async (args, ctx?: ActionRunContext) => {
+    await assertAccess("crm-connection", args.connectionId, "editor");
+    const db = getDb();
+    const [connection] = await db
+      .select()
+      .from(schema.crmConnections)
+      .where(
+        and(
+          eq(schema.crmConnections.id, args.connectionId),
+          accessFilter(
+            schema.crmConnections,
+            schema.crmConnectionShares,
+            undefined,
+            "editor",
+          ),
+        ),
+      )
+      .limit(1);
+    if (!connection || connection.status === "disconnected")
+      throw new Error("CRM connection is unavailable.");
+    if (
+      !isConnectedCrmProvider(connection.provider) ||
+      !connection.workspaceConnectionId
+    )
+      throw new Error(
+        "CRM sync requires a connected HubSpot or Salesforce workspace connection.",
+      );
+    const ownership = requireCrmScope(ctx);
+    const adapter = await createConnectedCrmAdapter({
+      provider: connection.provider,
+      connectionId: connection.workspaceConnectionId,
+      userEmail: ownership.ownerEmail,
+      orgId: ownership.orgId,
+    });
+    const result = await syncCrmMirror({
+      connectionId: connection.id,
+      objectType: args.objectType,
+      scope: { objectType: args.objectType, ...args.scope },
+      fieldAllowList: args.fieldAllowList,
+      allowCustomObject: args.allowCustomObject,
+      cursor: args.cursor,
+      pageSize: args.pageSize,
+      maxPages: args.maxPages,
+      ownership,
+      adapter,
+    });
+    return {
+      ...result,
+      ownerEmail: ownership.ownerEmail,
+      orgId: ownership.orgId,
+      visibility: ownership.visibility,
+    };
+  },
+});

package/corpus/templates/crm/actions/update-crm-attribute.ts

@@ -0,0 +1,111 @@
+import { defineAction } from "@agent-native/core/action";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import {
+  CRM_ATTRIBUTE_FILL_MODES,
+  CRM_ATTRIBUTE_TYPES,
+} from "../shared/crm-contract.js";
+import { toJson } from "./_crm-action-utils.js";
+import {
+  CrmAttributeValueError,
+  loadAttributeOptions,
+  requireEditableAttribute,
+  toAttributeDefinition,
+} from "./_crm-attribute-utils.js";
+
+const MAX_CONFIG_CHARS = 4000;
+
+export default defineAction({
+  description:
+    "Update one CRM attribute's presentation and behaviour: title, description, position, required, historyTracked, config, archived, and the manual fill mode. The api slug and the attribute type are immutable — every stored value row is keyed by the slug and typed by the type, so changing either would orphan history instead of migrating it. Setting fillMode never runs a fill; fills are triggered manually.",
+  schema: z.object({
+    attributeId: z.string().trim().min(1).max(128),
+    title: z.string().trim().min(1).max(200).optional(),
+    description: z.string().trim().max(2000).nullish(),
+    position: z.number().int().min(0).max(10_000).optional(),
+    required: z.boolean().optional(),
+    historyTracked: z.boolean().optional(),
+    config: z.record(z.string(), z.unknown()).optional(),
+    fillMode: z.enum(CRM_ATTRIBUTE_FILL_MODES).nullish(),
+    fillConfig: z.record(z.string(), z.unknown()).optional(),
+    archived: z.boolean().optional(),
+    apiSlug: z
+      .string()
+      .trim()
+      .min(1)
+      .max(128)
+      .optional()
+      .describe("Immutable. Supplying a different slug is rejected."),
+    type: z
+      .enum(CRM_ATTRIBUTE_TYPES)
+      .optional()
+      .describe("Immutable. Supplying a different type is rejected."),
+  }),
+  audit: {
+    target: (args) => ({ type: "crm-field-policy", id: args.attributeId }),
+    summary: (args) => `Updated CRM attribute ${args.attributeId}`,
+  },
+  run: async (args) => {
+    const current = await requireEditableAttribute(args.attributeId);
+
+    if (
+      args.apiSlug &&
+      args.apiSlug !== (current.apiSlug ?? current.fieldName)
+    ) {
+      throw new CrmAttributeValueError(
+        "crm-attribute-slug-immutable",
+        `The api slug of attribute ${args.attributeId} is "${current.apiSlug ?? current.fieldName}" and cannot change: every stored value row is keyed by it, so a rename would orphan the attribute's history. Create a new attribute instead.`,
+      );
+    }
+    if (args.type && args.type !== current.attributeType) {
+      throw new CrmAttributeValueError(
+        "crm-attribute-type-immutable",
+        `The type of attribute ${args.attributeId} is "${current.attributeType}" and cannot change: stored values live in the column that type chose, and reinterpreting them is a migration, not an edit. Create a new attribute and move the values.`,
+      );
+    }
+
+    const patch = {
+      ...(args.title === undefined ? {} : { label: args.title }),
+      ...(args.description === undefined
+        ? {}
+        : { description: args.description }),
+      ...(args.position === undefined ? {} : { position: args.position }),
+      ...(args.required === undefined ? {} : { required: args.required }),
+      ...(args.historyTracked === undefined
+        ? {}
+        : { historyTracked: args.historyTracked }),
+      ...(args.config === undefined
+        ? {}
+        : { configJson: toJson(args.config, MAX_CONFIG_CHARS) }),
+      ...(args.fillMode === undefined ? {} : { fillMode: args.fillMode }),
+      ...(args.fillConfig === undefined
+        ? {}
+        : { fillConfigJson: toJson(args.fillConfig, MAX_CONFIG_CHARS) }),
+      ...(args.archived === undefined ? {} : { archived: args.archived }),
+    };
+
+    const db = getDb();
+    if (Object.keys(patch).length > 0) {
+      await db
+        .update(schema.crmFieldPolicies)
+        .set({ ...patch, updatedAt: new Date().toISOString() })
+        .where(eq(schema.crmFieldPolicies.id, args.attributeId));
+    }
+
+    const [row] = await db
+      .select()
+      .from(schema.crmFieldPolicies)
+      .where(eq(schema.crmFieldPolicies.id, args.attributeId))
+      .limit(1);
+    if (!row) {
+      throw new Error("CRM attribute could not be verified after saving.");
+    }
+    const options = await loadAttributeOptions({
+      attributeIds: [row.id],
+      includeArchived: true,
+    });
+    return toAttributeDefinition(row, options.get(row.id) ?? []);
+  },
+});

package/corpus/templates/crm/actions/update-crm-list-entry.ts

@@ -0,0 +1,102 @@
+import { defineAction, type ActionRunContext } from "@agent-native/core/action";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { requireCrmScope } from "./_crm-action-utils.js";
+import {
+  crmActorFrom,
+  indexAttributes,
+  loadCrmListAttributes,
+  requireCrmList,
+  requireCrmListEntry,
+  writeCrmListEntryValues,
+} from "./_crm-list-utils.js";
+import { listEntryValuesSchema } from "./add-crm-record-to-list.js";
+
+export default defineAction({
+  description:
+    "Set values on a CRM list entry's own attributes and/or reorder it. Moving an entry to another stage is exactly this call: the previous value's row is closed and a new one opened, so time-in-stage is derivable from the entry's own history. Entry attributes belong to the list, not to the record — this never writes to the record or to a provider.",
+  schema: z.object({
+    entryId: z.string().trim().min(1).max(128),
+    values: listEntryValuesSchema.optional(),
+    position: z.number().int().min(0).max(100_000).optional(),
+  }),
+  audit: {
+    target: (_args, result) => {
+      const entry = result as {
+        entryId: string;
+        ownerEmail: string;
+        orgId: string | null;
+        visibility: "private" | "org" | "public";
+      };
+      return {
+        type: "crm-list-entry",
+        id: entry.entryId,
+        ownerEmail: entry.ownerEmail,
+        orgId: entry.orgId,
+        visibility: entry.visibility,
+      };
+    },
+    summary: (args) => `Updated CRM list entry ${args.entryId}`,
+    recordInputs: false,
+  },
+  run: async (args, ctx?: ActionRunContext) => {
+    const db = getDb();
+    const entry = await requireCrmListEntry(db, args.entryId, "editor");
+    const list = await requireCrmList(db, entry.listId, "editor");
+    const attributes = indexAttributes(
+      await loadCrmListAttributes(db, list.id),
+    );
+    const actor = crmActorFrom(ctx);
+    const now = new Date().toISOString();
+    // Value rows inherit the ENTRY's ownership, not the caller's, so an editor
+    // writing to a shared entry cannot fork its visibility.
+    const ownership = {
+      ownerEmail: entry.ownerEmail,
+      orgId: entry.orgId,
+      visibility: entry.visibility,
+    };
+    // Reject an unauthenticated caller the same way a fresh write would.
+    requireCrmScope(ctx);
+
+    const writes = await db.transaction(async (tx) => {
+      if (args.position !== undefined) {
+        await tx
+          .update(schema.crmListEntries)
+          .set({ position: args.position, updatedAt: now })
+          .where(
+            and(
+              eq(schema.crmListEntries.id, entry.id),
+              accessFilter(
+                schema.crmListEntries,
+                schema.crmListEntryShares,
+                undefined,
+                "editor",
+              ),
+            ),
+          );
+      }
+      return writeCrmListEntryValues({
+        db: tx,
+        recordId: entry.recordId,
+        entryId: entry.id,
+        attributes,
+        values: args.values ?? {},
+        actor,
+        ownership,
+        now,
+      });
+    });
+
+    return {
+      entryId: entry.id,
+      listId: list.id,
+      recordId: entry.recordId,
+      position: args.position ?? entry.position,
+      values: writes,
+      ...ownership,
+    };
+  },
+});