@agent-native/core 0.123.0 → 0.123.1

package/corpus/templates/crm/actions/list-crm-list-entries.ts

@@ -0,0 +1,192 @@
+import { defineAction } from "@agent-native/core/action";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, asc, eq, type SQL } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import {
+  attributeSummary,
+  buildEntryFilter,
+  buildEntryOrder,
+  CRM_ENTRY_BUILTIN_FIELDS,
+  CRM_ENTRY_FILTER_OPERATORS,
+  CrmEntryFieldResolver,
+  decodeCrmCursor,
+  indexAttributes,
+  loadCrmEntryValues,
+  loadCrmListAttributes,
+  MAX_LIST_ENTRY_FILTERS,
+  MAX_LIST_ENTRY_LIMIT,
+  MAX_LIST_ENTRY_SORTS,
+  requireCrmList,
+} from "./_crm-list-utils.js";
+
+const filterValueSchema = z.union([
+  z.string().max(500),
+  z.number(),
+  z.boolean(),
+  z.null(),
+  z.array(z.union([z.string().max(500), z.number(), z.boolean()])).max(50),
+]);
+
+export default defineAction({
+  description:
+    "Read a bounded page of entries in a CRM list with each entry's record summary and its own entry attribute values. Filters, sorting, and pagination are applied in SQL, so a filtered page is the real result set and not one page narrowed afterwards. Filter and sort fields are a list attribute's api_slug or one of the built-in fields.",
+  schema: z.object({
+    listId: z.string().trim().min(1).max(128),
+    filters: z
+      .array(
+        z.object({
+          attribute: z
+            .string()
+            .trim()
+            .min(1)
+            .max(120)
+            .describe(
+              `A list attribute api_slug, or one of: ${CRM_ENTRY_BUILTIN_FIELDS.join(", ")}.`,
+            ),
+          operator: z.enum(CRM_ENTRY_FILTER_OPERATORS),
+          value: filterValueSchema.optional(),
+        }),
+      )
+      .max(MAX_LIST_ENTRY_FILTERS)
+      .optional(),
+    sort: z
+      .array(
+        z.object({
+          attribute: z.string().trim().min(1).max(120),
+          direction: z.enum(["asc", "desc"]).default("asc"),
+        }),
+      )
+      .max(MAX_LIST_ENTRY_SORTS)
+      .optional(),
+    limit: z.coerce.number().int().min(1).max(MAX_LIST_ENTRY_LIMIT).default(50),
+    cursor: z
+      .string()
+      .regex(/^\d+$/)
+      .optional()
+      .describe("Cursor returned by a previous page."),
+  }),
+  http: { method: "POST" },
+  readOnly: true,
+  run: async (args) => {
+    const db = getDb();
+    const list = await requireCrmList(db, args.listId, "viewer");
+    const attributes = await loadCrmListAttributes(db, list.id);
+    const bySlug = indexAttributes(attributes);
+
+    const resolver = new CrmEntryFieldResolver(bySlug);
+    // Filters and sorts are resolved before the query is built: resolving a
+    // field is what registers the LEFT JOIN it needs.
+    const conditions: SQL[] = (args.filters ?? []).map((filter) =>
+      buildEntryFilter(resolver, filter),
+    );
+    const order = (args.sort ?? []).flatMap((sort) =>
+      buildEntryOrder(resolver, sort),
+    );
+
+    const offset = decodeCrmCursor(args.cursor);
+    const limit = Math.min(args.limit, MAX_LIST_ENTRY_LIMIT);
+
+    let query = db
+      .select({
+        entryId: schema.crmListEntries.id,
+        position: schema.crmListEntries.position,
+        createdAt: schema.crmListEntries.createdAt,
+        createdByActorType: schema.crmListEntries.createdByActorType,
+        createdByActorId: schema.crmListEntries.createdByActorId,
+        recordId: schema.crmRecords.id,
+        objectType: schema.crmRecords.objectType,
+        kind: schema.crmRecords.kind,
+        displayName: schema.crmRecords.displayName,
+        primaryEmail: schema.crmRecords.primaryEmail,
+        domain: schema.crmRecords.domain,
+        recordStage: schema.crmRecords.stage,
+        ownerName: schema.crmRecords.ownerName,
+        amount: schema.crmRecords.amount,
+        currencyCode: schema.crmRecords.currencyCode,
+        closeDate: schema.crmRecords.closeDate,
+        recordUpdatedAt: schema.crmRecords.updatedAt,
+      })
+      .from(schema.crmListEntries)
+      .innerJoin(
+        schema.crmRecords,
+        eq(schema.crmRecords.id, schema.crmListEntries.recordId),
+      )
+      .$dynamic();
+
+    for (const join of resolver.joins) {
+      query = query.leftJoin(join.table, join.on);
+    }
+
+    const rows = await query
+      .where(
+        and(
+          eq(schema.crmListEntries.listId, list.id),
+          ...conditions,
+          accessFilter(schema.crmListEntries, schema.crmListEntryShares),
+          accessFilter(schema.crmRecords, schema.crmRecordShares),
+        ),
+      )
+      .orderBy(
+        ...order,
+        asc(schema.crmListEntries.position),
+        asc(schema.crmListEntries.createdAt),
+        asc(schema.crmListEntries.id),
+      )
+      .limit(limit + 1)
+      .offset(offset);
+
+    const page = rows.slice(0, limit);
+    const values = await loadCrmEntryValues(
+      db,
+      page.map((row) => row.entryId),
+      bySlug,
+    );
+
+    return {
+      list: {
+        id: list.id,
+        name: list.name,
+        apiSlug: list.apiSlug,
+        parentObjectType: list.parentObjectType,
+        defaultViewId: list.defaultViewId,
+        archived: list.archived,
+      },
+      attributes: attributes.map(attributeSummary),
+      entries: page.map((row) => {
+        const entryValues = values.get(row.entryId) ?? {
+          values: {},
+          valuesSince: {},
+        };
+        return {
+          id: row.entryId,
+          listId: list.id,
+          recordId: row.recordId,
+          position: row.position,
+          createdAt: row.createdAt,
+          createdByActorType: row.createdByActorType,
+          createdByActorId: row.createdByActorId,
+          record: {
+            id: row.recordId,
+            objectType: row.objectType,
+            kind: row.kind,
+            displayName: row.displayName,
+            primaryEmail: row.primaryEmail,
+            domain: row.domain,
+            stage: row.recordStage,
+            ownerName: row.ownerName,
+            amount: row.amount,
+            currencyCode: row.currencyCode,
+            closeDate: row.closeDate,
+            updatedAt: row.recordUpdatedAt,
+          },
+          values: entryValues.values,
+          valuesSince: entryValues.valuesSince,
+        };
+      }),
+      nextCursor: rows.length > limit ? String(offset + limit) : undefined,
+      complete: rows.length <= limit,
+    };
+  },
+});

package/corpus/templates/crm/actions/list-crm-lists.ts

@@ -0,0 +1,80 @@
+import { defineAction } from "@agent-native/core/action";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, asc, count, eq, inArray } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { queryFlag } from "./_crm-action-utils.js";
+import { decodeCrmCursor, MAX_LIST_LIMIT } from "./_crm-list-utils.js";
+
+export default defineAction({
+  description:
+    "List the access-scoped CRM lists with their entry counts. A list is a workflow overlay over one object type; its entries and entry attribute values are always local, never provider rows.",
+  schema: z.object({
+    connectionId: z.string().trim().min(1).max(128).optional(),
+    includeArchived: queryFlag.describe(
+      "Include archived lists so they can be inspected or restored.",
+    ),
+    limit: z.coerce.number().int().min(1).max(MAX_LIST_LIMIT).default(50),
+    cursor: z
+      .string()
+      .regex(/^\d+$/)
+      .optional()
+      .describe("Cursor returned by a previous page."),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (args) => {
+    const db = getDb();
+    const offset = decodeCrmCursor(args.cursor);
+    const limit = Math.min(args.limit, MAX_LIST_LIMIT);
+
+    const rows = await db
+      .select()
+      .from(schema.crmLists)
+      .where(
+        and(
+          ...(args.connectionId
+            ? [eq(schema.crmLists.connectionId, args.connectionId)]
+            : []),
+          ...(args.includeArchived
+            ? []
+            : [eq(schema.crmLists.archived, false)]),
+          accessFilter(schema.crmLists, schema.crmListShares),
+        ),
+      )
+      .orderBy(asc(schema.crmLists.position), asc(schema.crmLists.createdAt))
+      .limit(limit + 1)
+      .offset(offset);
+
+    const page = rows.slice(0, limit);
+    const listIds = page.map((list) => list.id);
+    const countRows = listIds.length
+      ? await db
+          .select({
+            listId: schema.crmListEntries.listId,
+            entries: count(),
+          })
+          .from(schema.crmListEntries)
+          .where(
+            and(
+              inArray(schema.crmListEntries.listId, listIds),
+              accessFilter(schema.crmListEntries, schema.crmListEntryShares),
+            ),
+          )
+          .groupBy(schema.crmListEntries.listId)
+      : [];
+    const entryCounts = new Map(
+      countRows.map((row) => [row.listId, Number(row.entries)]),
+    );
+
+    return {
+      lists: page.map((list) => ({
+        ...list,
+        entryCount: entryCounts.get(list.id) ?? 0,
+      })),
+      nextCursor: rows.length > limit ? String(offset + limit) : undefined,
+      complete: rows.length <= limit,
+    };
+  },
+});

package/corpus/templates/crm/actions/list-crm-proposals.ts

@@ -0,0 +1,55 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { resolveProviderRecordLinks } from "../server/crm/provider-record-link.js";
+import { listCrmProposals } from "../server/db/crm-store.js";
+
+export default defineAction({
+  description:
+    "List bounded, access-scoped CRM mutation proposals, their review status, and the upstream record link for completing a provider change by hand. Proposal payloads are intentionally omitted from this list surface. A proposal with status `approved` and no `appliedAt` was prepared and handed off — CRM never wrote it upstream.",
+  schema: z.object({
+    recordId: z.string().min(1).optional(),
+    status: z
+      .enum([
+        "pending",
+        "approved",
+        "applied",
+        "rejected",
+        "conflict",
+        "failed",
+      ])
+      .optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+    cursor: z
+      .string()
+      .regex(/^\d+$/)
+      .optional()
+      .describe("Cursor returned by a previous page."),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (input) => {
+    const result = await listCrmProposals(input);
+    const links = await resolveProviderRecordLinks(
+      result.proposals
+        .map((proposal) => proposal.recordId)
+        .filter((recordId): recordId is string => Boolean(recordId)),
+    );
+    return {
+      ...result,
+      proposals: result.proposals.map((proposal) => {
+        const link = proposal.recordId
+          ? links.get(proposal.recordId)
+          : undefined;
+        // A missing link is reported, never blanked: the review surface has to
+        // say why it cannot hand off rather than show a dead button.
+        return {
+          ...proposal,
+          recordUrl: link?.available ? link.url : null,
+          recordUrlUnavailableReason:
+            link && !link.available ? link.reason : null,
+        };
+      }),
+    };
+  },
+});

package/corpus/templates/crm/actions/list-crm-record-field-history.ts

@@ -0,0 +1,201 @@
+/**
+ * The bitemporal history of one attribute value.
+ *
+ * `crm_record_fields` keeps every superseded value as its own row stamped with
+ * when it stopped being current, so "changed from X to Y, by Z" is a read, not
+ * an audit-log join. An attribute with `history_tracked = false` is updated in
+ * place and therefore genuinely HAS no history — that is reported as
+ * `historyTracked: false`, which is a different answer from "nothing changed".
+ */
+
+import { defineAction } from "@agent-native/core/action";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, desc, eq, isNull, sql } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { CrmAttributeValueError } from "../server/lib/record-fields.js";
+import { storageColumnFor } from "../shared/crm-attributes.js";
+import type { CrmValue } from "../shared/crm-contract.js";
+
+const MAX_CHANGES = 50;
+
+export default defineAction({
+  description:
+    "Return the bitemporal change history of one CRM attribute value, newest first: each stored value with the window it was current for and the actor that set it. Pass entryId to read a list-entry attribute (a stage history) instead of a record attribute. historyTracked=false means the attribute is updated in place and keeps no history, which is not the same as no changes.",
+  schema: z.object({
+    recordId: z.string().trim().min(1).max(128),
+    apiSlug: z.string().trim().min(1).max(120),
+    entryId: z
+      .string()
+      .trim()
+      .min(1)
+      .max(128)
+      .optional()
+      .describe(
+        "Read a list-entry attribute's history instead of the record's.",
+      ),
+    limit: z.coerce.number().int().min(1).max(MAX_CHANGES).default(20),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (args) => {
+    const db = getDb();
+    const [record] = await db
+      .select({
+        id: schema.crmRecords.id,
+        connectionId: schema.crmRecords.connectionId,
+        objectType: schema.crmRecords.objectType,
+      })
+      .from(schema.crmRecords)
+      .where(
+        and(
+          eq(schema.crmRecords.id, args.recordId),
+          accessFilter(schema.crmRecords, schema.crmRecordShares),
+        ),
+      )
+      .limit(1);
+    if (!record) {
+      const error = new Error("CRM record not found") as Error & {
+        statusCode?: number;
+      };
+      error.statusCode = 404;
+      throw error;
+    }
+
+    let attributeScope: { target: "object" | "list"; targetId: string };
+    if (args.entryId) {
+      const [entry] = await db
+        .select({ listId: schema.crmListEntries.listId })
+        .from(schema.crmListEntries)
+        .where(
+          and(
+            eq(schema.crmListEntries.id, args.entryId),
+            eq(schema.crmListEntries.recordId, record.id),
+            accessFilter(schema.crmListEntries, schema.crmListEntryShares),
+          ),
+        )
+        .limit(1);
+      if (!entry) {
+        throw new CrmAttributeValueError(
+          "crm-list-entry-not-found",
+          `CRM list entry "${args.entryId}" was not found on this record.`,
+        );
+      }
+      attributeScope = { target: "list", targetId: entry.listId };
+    } else {
+      attributeScope = { target: "object", targetId: record.objectType };
+    }
+
+    const [attribute] = await db
+      .select({
+        id: schema.crmFieldPolicies.id,
+        apiSlug: schema.crmFieldPolicies.apiSlug,
+        fieldName: schema.crmFieldPolicies.fieldName,
+        label: schema.crmFieldPolicies.label,
+        attributeType: schema.crmFieldPolicies.attributeType,
+        multi: schema.crmFieldPolicies.multi,
+        historyTracked: schema.crmFieldPolicies.historyTracked,
+      })
+      .from(schema.crmFieldPolicies)
+      .where(
+        and(
+          eq(schema.crmFieldPolicies.target, attributeScope.target),
+          eq(schema.crmFieldPolicies.objectType, attributeScope.targetId),
+          eq(schema.crmFieldPolicies.fieldName, args.apiSlug),
+          accessFilter(schema.crmFieldPolicies, schema.crmFieldPolicyShares),
+        ),
+      )
+      .limit(1);
+    if (!attribute) {
+      throw new CrmAttributeValueError(
+        "crm-attribute-not-found",
+        `"${args.apiSlug}" is not an attribute of ${attributeScope.target} "${attributeScope.targetId}".`,
+      );
+    }
+
+    const column = storageColumnFor(attribute.attributeType, attribute.multi);
+    const rows = await db
+      .select({
+        id: schema.crmRecordFields.id,
+        stringValue: schema.crmRecordFields.stringValue,
+        numberValue: schema.crmRecordFields.numberValue,
+        booleanValue: schema.crmRecordFields.booleanValue,
+        jsonValue: schema.crmRecordFields.jsonValue,
+        activeFrom: schema.crmRecordFields.activeFrom,
+        activeUntil: schema.crmRecordFields.activeUntil,
+        actorType: schema.crmRecordFields.actorType,
+        actorId: schema.crmRecordFields.actorId,
+      })
+      .from(schema.crmRecordFields)
+      .where(
+        and(
+          eq(schema.crmRecordFields.recordId, record.id),
+          args.entryId
+            ? eq(schema.crmRecordFields.entryId, args.entryId)
+            : isNull(schema.crmRecordFields.entryId),
+          eq(schema.crmRecordFields.fieldName, args.apiSlug),
+          accessFilter(schema.crmRecordFields, schema.crmRecordFieldShares),
+        ),
+      )
+      // Two writes can land in the same millisecond, so `activeFrom` alone does
+      // not order the chain. The current row is first, then closed rows by when
+      // they were closed — a row's `activeUntil` is the next row's `activeFrom`,
+      // which is what actually orders same-instant edits. `(x is null) desc`
+      // puts the current row first in both SQLite (1 > 0) and PostgreSQL
+      // (true > false); NULLS FIRST/LAST defaults differ and cannot be relied on.
+      .orderBy(
+        desc(sql`(${schema.crmRecordFields.activeUntil} is null)`),
+        desc(schema.crmRecordFields.activeUntil),
+        desc(schema.crmRecordFields.activeFrom),
+        desc(schema.crmRecordFields.id),
+      )
+      .limit(args.limit);
+
+    return {
+      recordId: record.id,
+      entryId: args.entryId ?? null,
+      apiSlug: attribute.apiSlug ?? attribute.fieldName,
+      label: attribute.label,
+      attributeType: attribute.attributeType,
+      multi: attribute.multi,
+      historyTracked: attribute.historyTracked,
+      changes: rows.map((row) => ({
+        id: row.id,
+        value: decodeHistoryValue(column, args.apiSlug, row) as CrmValue,
+        activeFrom: row.activeFrom,
+        activeUntil: row.activeUntil,
+        current: row.activeUntil === null,
+        actorType: row.actorType,
+        actorId: row.actorId,
+      })),
+      complete: rows.length < args.limit,
+    };
+  },
+});
+
+function decodeHistoryValue(
+  column: ReturnType<typeof storageColumnFor>,
+  apiSlug: string,
+  row: {
+    stringValue: string | null;
+    numberValue: number | null;
+    booleanValue: boolean | null;
+    jsonValue: string | null;
+  },
+): CrmValue {
+  if (column === "numberValue") return row.numberValue;
+  if (column === "booleanValue") return row.booleanValue;
+  if (column === "jsonValue") {
+    if (row.jsonValue === null) return null;
+    try {
+      return JSON.parse(row.jsonValue) as CrmValue;
+    } catch {
+      throw new CrmAttributeValueError(
+        "crm-attribute-value-unreadable",
+        `A stored history value for "${apiSlug}" is not readable JSON. It was written outside the attribute writer.`,
+      );
+    }
+  }
+  return row.stringValue;
+}