@agent-native/core 0.123.0 → 0.123.1

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

@@ -0,0 +1,194 @@
+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 {
+  CrmListError,
+  crmApiSlug,
+  uniqueCrmListSlug,
+} from "./_crm-list-utils.js";
+
+/**
+ * A new list is useless without somewhere to move entries to, so it is seeded
+ * with a `status` attribute. It lives on the list, not on the record: two
+ * entries for the same account can sit in different stages.
+ */
+const DEFAULT_STAGE_OPTIONS = [
+  { value: "new", title: "New" },
+  { value: "in-progress", title: "In Progress" },
+  { value: "won", title: "Won", celebrate: true },
+  { value: "lost", title: "Lost" },
+] as const;
+
+async function resolveConnectionId(
+  db: ReturnType<typeof getDb>,
+  connectionId: string | undefined,
+): Promise<string> {
+  const rows = await db
+    .select({ id: schema.crmConnections.id })
+    .from(schema.crmConnections)
+    .where(
+      and(
+        ...(connectionId ? [eq(schema.crmConnections.id, connectionId)] : []),
+        accessFilter(
+          schema.crmConnections,
+          schema.crmConnectionShares,
+          undefined,
+          "editor",
+        ),
+      ),
+    )
+    .limit(connectionId ? 1 : 2);
+  if (!rows.length) {
+    throw new CrmListError(
+      "crm-connection-unavailable",
+      connectionId
+        ? "The selected CRM connection is unavailable or you do not have editor access."
+        : "Configure a CRM before creating a list.",
+    );
+  }
+  if (!connectionId && rows.length > 1) {
+    throw new CrmListError(
+      "crm-connection-ambiguous",
+      "More than one CRM connection is available. Provide connectionId to choose one.",
+    );
+  }
+  return rows[0]!.id;
+}
+
+export default defineAction({
+  description:
+    "Create a CRM list — a workflow overlay over one object type, with its own entry attributes. Lists and their entries are local-authoritative on every backend, including HubSpot and Salesforce, so a pipeline never needs a provider write. Seeds a Stage attribute unless seedStageAttribute is false.",
+  schema: z.object({
+    connectionId: z.string().trim().min(1).max(128).optional(),
+    name: z.string().trim().min(1).max(120),
+    parentObjectType: z
+      .string()
+      .trim()
+      .min(1)
+      .max(120)
+      .describe(
+        "Object type whose records may be added, e.g. accounts, people, opportunities.",
+      ),
+    description: z.string().trim().max(500).optional(),
+    position: z.number().int().min(0).max(100_000).optional(),
+    seedStageAttribute: z.boolean().default(true),
+  }),
+  audit: {
+    target: (_args, result) => {
+      const list = result as {
+        id: string;
+        ownerEmail: string;
+        orgId: string | null;
+        visibility: "private" | "org";
+      };
+      return {
+        type: "crm-list",
+        id: list.id,
+        ownerEmail: list.ownerEmail,
+        orgId: list.orgId,
+        visibility: list.visibility,
+      };
+    },
+    summary: (args) => `Created CRM list ${args.name}`,
+  },
+  run: async (args, ctx?: ActionRunContext) => {
+    const ownership = requireCrmScope(ctx);
+    const db = getDb();
+    const connectionId = await resolveConnectionId(db, args.connectionId);
+    const apiSlug = await uniqueCrmListSlug(
+      db,
+      connectionId,
+      crmApiSlug(args.name),
+    );
+    const listId = crypto.randomUUID();
+    const now = new Date().toISOString();
+
+    const stageAttributeId = args.seedStageAttribute
+      ? crypto.randomUUID()
+      : null;
+
+    await db.transaction(async (tx) => {
+      await tx.insert(schema.crmLists).values({
+        id: listId,
+        connectionId,
+        name: args.name,
+        apiSlug,
+        parentObjectType: args.parentObjectType,
+        description: args.description ?? "",
+        defaultViewId: null,
+        archived: false,
+        position: args.position ?? 0,
+        source: "local",
+        ...ownership,
+        createdAt: now,
+        updatedAt: now,
+      });
+
+      if (!stageAttributeId) return;
+
+      await tx.insert(schema.crmFieldPolicies).values({
+        id: stageAttributeId,
+        connectionId,
+        // `object_type` mirrors `target_id` for list attributes so the legacy
+        // (connection_id, object_type, field_name) unique index keeps working.
+        objectType: listId,
+        fieldName: "stage",
+        label: "Stage",
+        valueType: "enum",
+        storagePolicy: "local-authoritative",
+        sensitive: false,
+        readable: true,
+        createable: true,
+        updateable: true,
+        required: false,
+        attributeType: "status",
+        target: "list",
+        targetId: listId,
+        apiSlug: "stage",
+        multi: false,
+        authority: "local-authoritative",
+        historyTracked: true,
+        uniqueValue: false,
+        archived: false,
+        position: 0,
+        ...ownership,
+        createdAt: now,
+        updatedAt: now,
+      });
+
+      await tx.insert(schema.crmAttributeOptions).values(
+        DEFAULT_STAGE_OPTIONS.map((option, index) => ({
+          id: crypto.randomUUID(),
+          attributeId: stageAttributeId,
+          value: option.value,
+          title: option.title,
+          position: index,
+          archived: false,
+          celebrate: "celebrate" in option ? option.celebrate : false,
+          ...ownership,
+          createdAt: now,
+          updatedAt: now,
+        })),
+      );
+    });
+
+    const [list] = await db
+      .select()
+      .from(schema.crmLists)
+      .where(
+        and(
+          eq(schema.crmLists.id, listId),
+          accessFilter(schema.crmLists, schema.crmListShares),
+        ),
+      )
+      .limit(1);
+    if (!list) {
+      throw new Error("CRM list could not be verified after creation.");
+    }
+    return { ...list, stageAttributeId };
+  },
+});

package/corpus/templates/crm/actions/create-crm-record.ts

@@ -0,0 +1,148 @@
+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 {
+  configureNativeCrmConnection,
+  createNativeCrmAdapter,
+} from "../server/crm/native-adapter.js";
+import { getDb, schema } from "../server/db/index.js";
+import type { CrmValue } from "../shared/crm-contract.js";
+import {
+  crmInitiatedBy,
+  isSafeCrmMutationFields,
+  MAX_CRM_FIELDS_PER_MUTATION,
+  requireCrmScope,
+  scopedCrmIdempotencyKey,
+} from "./_crm-action-utils.js";
+
+const kindToObjectType = {
+  account: "accounts",
+  person: "people",
+  opportunity: "opportunities",
+} as const;
+
+export const nativeRecordFieldsSchema = z
+  .record(z.string().trim().min(1).max(120), z.unknown())
+  .refine(
+    (fields) => Object.keys(fields).length <= MAX_CRM_FIELDS_PER_MUTATION,
+    `Provide at most ${MAX_CRM_FIELDS_PER_MUTATION} fields.`,
+  )
+  .refine(
+    isSafeCrmMutationFields,
+    "CRM fields and values cannot contain media, transcripts, data URLs, base64, or oversized JSON.",
+  );
+
+export default defineAction({
+  description:
+    "Create an account, person, or opportunity in Native SQL CRM. The record is local-authoritative, access-scoped, idempotent, audited, and has no upstream provider write.",
+  schema: z.object({
+    connectionId: z.string().trim().min(1).max(128).optional(),
+    kind: z.enum(["account", "person", "opportunity"]),
+    displayName: z.string().trim().min(1).max(500),
+    fields: nativeRecordFieldsSchema.optional(),
+    idempotencyKey: z.string().trim().min(1).max(256).optional(),
+  }),
+  audit: {
+    target: (_args, result) => {
+      const record = result as {
+        recordId: string;
+        ownerEmail: string;
+        orgId: string | null;
+        visibility: "private" | "org";
+      };
+      return {
+        type: "crm-record",
+        id: record.recordId,
+        ownerEmail: record.ownerEmail,
+        orgId: record.orgId,
+        visibility: record.visibility,
+      };
+    },
+    summary: (args) =>
+      `Created Native SQL CRM ${args.kind} ${args.displayName}`,
+    recordInputs: false,
+  },
+  run: async (args, ctx?: ActionRunContext) => {
+    const ownership = requireCrmScope(ctx);
+    const db = getDb();
+    const connectionRows = await db
+      .select({ id: schema.crmConnections.id })
+      .from(schema.crmConnections)
+      .where(
+        and(
+          eq(schema.crmConnections.provider, "native"),
+          ...(args.connectionId
+            ? [eq(schema.crmConnections.id, args.connectionId)]
+            : []),
+          accessFilter(
+            schema.crmConnections,
+            schema.crmConnectionShares,
+            undefined,
+            "editor",
+          ),
+        ),
+      )
+      .limit(args.connectionId ? 1 : 2);
+    if (!connectionRows.length && args.connectionId) {
+      throw new Error(
+        "The selected Native SQL CRM is unavailable or you do not have editor access.",
+      );
+    }
+    if (!args.connectionId && connectionRows.length > 1) {
+      throw new Error(
+        "More than one Native SQL CRM is available. Provide connectionId to choose one.",
+      );
+    }
+    const connectionId =
+      connectionRows[0]?.id ??
+      (
+        await configureNativeCrmConnection({
+          ownership,
+        })
+      ).id;
+    const objectType = kindToObjectType[args.kind];
+    const remoteId = crypto.randomUUID();
+    const fields = {
+      ...(args.fields as Record<string, CrmValue> | undefined),
+      displayName: args.displayName,
+      ...(args.kind === "person" ? {} : { name: args.displayName }),
+    };
+    const idempotencyKey = await scopedCrmIdempotencyKey({
+      ...ownership,
+      recordId: `${connectionId}:${objectType}`,
+      key: args.idempotencyKey ?? crypto.randomUUID(),
+    });
+    const adapter = await createNativeCrmAdapter({
+      connectionId,
+      initiatedBy: crmInitiatedBy(ctx),
+    });
+    const result = await adapter.applyMutation({
+      operation: "create",
+      record: {
+        connectionId,
+        provider: "native",
+        objectType,
+        kind: args.kind,
+        remoteId,
+      },
+      fields,
+      idempotencyKey,
+    });
+    if (result.status !== "applied" || !result.record?.ref.localId) {
+      throw new Error(
+        result.message ?? "Native SQL CRM record was not created.",
+      );
+    }
+    return {
+      recordId: result.record.ref.localId,
+      connectionId,
+      provider: "native" as const,
+      kind: args.kind,
+      displayName: result.record.displayName,
+      revision: result.remoteRevision,
+      ...ownership,
+    };
+  },
+});

package/corpus/templates/crm/actions/create-crm-signal-tracker.ts

@@ -0,0 +1,58 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { requireCrmScope } from "./_crm-action-utils.js";
+
+export default defineAction({
+  description:
+    "Create a bounded keyword or delegated-agent CRM signal detector. Smart detectors define criteria only; this action never calls a model.",
+  schema: z
+    .object({
+      name: z.string().trim().min(1).max(120),
+      description: z.string().trim().max(500).default(""),
+      kind: z.enum(["keyword", "smart"]),
+      keywords: z.array(z.string().trim().min(1).max(80)).max(40).default([]),
+      classifierPrompt: z.string().trim().max(1_000).default(""),
+      enabled: z.boolean().default(true),
+    })
+    .superRefine((value, ctx) => {
+      if (value.kind === "keyword" && value.keywords.length === 0) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["keywords"],
+          message: "Keyword detectors require at least one keyword.",
+        });
+      }
+      if (value.kind === "smart" && !value.classifierPrompt) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["classifierPrompt"],
+          message: "Smart detectors require a classification criterion.",
+        });
+      }
+    }),
+  run: async (args, ctx) => {
+    const scope = requireCrmScope(ctx);
+    const now = new Date().toISOString();
+    const id = crypto.randomUUID();
+    await getDb()
+      .insert(schema.crmSignalTrackers)
+      .values({
+        id,
+        name: args.name,
+        description: args.description,
+        kind: args.kind,
+        keywordsJson: JSON.stringify(
+          args.kind === "keyword" ? args.keywords : [],
+        ),
+        classifierPrompt: args.kind === "smart" ? args.classifierPrompt : "",
+        enabled: args.enabled,
+        isDefault: false,
+        ...scope,
+        createdAt: now,
+        updatedAt: now,
+      });
+    return { id, ...args };
+  },
+});

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

@@ -0,0 +1,68 @@
+import { defineAction } from "@agent-native/core/action";
+import { assertAccess } from "@agent-native/core/sharing";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+
+export default defineAction({
+  description:
+    "Delete one access-scoped saved CRM view and its shares. This removes a presentation setting only; it never deletes CRM records.",
+  schema: z.object({
+    id: z.string().trim().min(1).max(128),
+    expectedUpdatedAt: z
+      .string()
+      .min(1)
+      .max(64)
+      .optional()
+      .describe("Reject the delete when the view changed since it was read."),
+  }),
+  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) => `Deleted CRM saved view ${args.id}`,
+  },
+  run: async (args) => {
+    await assertAccess("crm-saved-view", args.id, "editor");
+    const db = getDb();
+    const [view] = await db
+      .select()
+      .from(schema.crmSavedViews)
+      .where(eq(schema.crmSavedViews.id, args.id))
+      .limit(1);
+    if (!view) throw new Error("CRM saved view was not found.");
+    if (
+      args.expectedUpdatedAt !== undefined &&
+      args.expectedUpdatedAt !== view.updatedAt
+    ) {
+      const error = new Error(
+        `CRM saved view "${args.id}" changed since it was read (expected ${args.expectedUpdatedAt}, found ${view.updatedAt}).`,
+      ) as Error & { statusCode?: number };
+      error.statusCode = 409;
+      throw error;
+    }
+
+    await db
+      .delete(schema.crmSavedViews)
+      .where(eq(schema.crmSavedViews.id, args.id));
+    await db
+      .delete(schema.crmSavedViewShares)
+      .where(eq(schema.crmSavedViewShares.resourceId, args.id));
+    // A dashboard-backed view keeps its data program: the program is a separate
+    // shareable resource that other views may reference.
+    return { ...view, deleted: true };
+  },
+});

package/corpus/templates/crm/actions/delete-staged-dataset.ts

@@ -0,0 +1,14 @@
+import { createDeleteStagedDatasetAction } from "@agent-native/core/provider-api/actions/staged-datasets";
+import { getCredentialContext } from "@agent-native/core/server/request-context";
+import { z } from "zod";
+
+import { CRM_APP_ID } from "../server/lib/provider-api.js";
+
+export default createDeleteStagedDatasetAction({
+  description:
+    "Delete a caller-scoped staged dataset after CRM analysis is complete.",
+  schema: z.object({ datasetId: z.string().min(1) }),
+  appId: CRM_APP_ID,
+  getOwnerEmail: () => getCredentialContext()?.userEmail ?? null,
+  http: false,
+});