git clone https://github.com/cogover/custom-backend-module-starter-project.git records-demo
cd records-demo
npm install --global @cogover/dev-cli@latest
npm install
npm install @cogover/sdk@latest
cogover-dev --version
npm ls @cogover/sdk typescript
cp cogover.example.json cogover.json

{
  "version": 1,
  "runtimeUrl": "https://{WORKSPACE_DOMAIN}",
  "projectId": "{PROJECT_ID}",
  "projectSlug": "records_demo"
}

COGOVER_API_KEY={WORKSPACE_API_KEY}

set -a; . ./.env; set +a
curl -sSf -X POST 'https://{WORKSPACE_DOMAIN}/bapi/v1/objects/list' \
  -H "Authorization: Bearer $COGOVER_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"slugs":["opportunity","account"],"includeFields":true}' \
  -o objects.json \
  && npx cogover-generate-workspace-types objects.json src/workspace.d.ts \
  && rm objects.json

declare module "@cogover/sdk" {
  interface WorkspaceObjects {
    // ...
    opportunity: {
      account: RecordReference<"account">;
      est_revenue: number | null;
      name: string;
      owner: RecordReference<"personnel"> | null;
      stage: "closed_won" | "negotiation" | "closed_lost" | "needs_analysis" | "proposal";
      // ...
    };
  }
}

import { createRouter } from "@cogover/sdk";
 
const router = createRouter();
const ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
const OPEN_STAGES = ["needs_analysis", "proposal", "negotiation"] as const;
const OPPORTUNITY_FIELDS = ["name", "stage", "est_revenue", "account"] as const;
 
router.get("/opportunities", async ({ data }) => {
  const opportunities = data.object("opportunity");
  const page = await opportunities.records.list({
    fields: OPPORTUNITY_FIELDS,
    where: opportunities.fields.stage.in(OPEN_STAGES),
    orderBy: [opportunities.fields.est_revenue.desc()],
    limit: 3,
  });
  return {
    total: page.total,
    opportunities: page.items.map(item => ({
      id: item.id,
      name: item.fields.name,
      stage: item.fields.stage,
      estRevenue: item.fields.est_revenue,
      account: item.fields.account,
    })),
  };
});
 
router.get("/opportunities/:opportunityId", async ({ data, request, response }) => {
  const opportunityId = request.params.opportunityId ?? "";
  if (!ID_PATTERN.test(opportunityId)) {
    return response.json({ error: "A valid opportunity id is required" }, { status: 400 });
  }
  const opportunity = await data.object("opportunity").records.get(opportunityId, {
    fields: OPPORTUNITY_FIELDS,
  });
  if (opportunity === null) {
    return response.json({ error: "Opportunity not found" }, { status: 404 });
  }
  return opportunity;
});
 
export default router.toHandler();

npm run build

src/main.ts(23,32): error TS2339: Property 'probability' does not exist on type 'Readonly<Pick<{ ... }, "account" | ... 2 more ... | "est_revenue">>'.

cogover-dev login --profile records_demo
cogover-dev doctor --profile records_demo
COGOVER_LOCAL_PORT=3100 cogover-dev run --profile records_demo --allow-writes=false -- npm run dev

curl -s 'http://127.0.0.1:3100/api/v1/ts-projects/records_demo/opportunities' | jq

{
  "total": 9,
  "opportunities": [
    {
      "id": "OPPXXXXXXXXXX01",
      "name": "RRE-Acme POS rollout",
      "stage": "proposal",
      "estRevenue": 120000000,
      "account": {
        "name": "",
        "id": "ACCXXXXXXXXXX01",
        "objectSlug": "account"
      }
    },
    {
      "id": "OPPXXXXXXXXXX02",
      "name": "RRE-Acme loyalty app",
      "stage": "negotiation",
      "estRevenue": 80000000,
      "account": {
        "name": "",
        "id": "ACCXXXXXXXXXX01",
        "objectSlug": "account"
      }
    },
    {
      "id": "OPPXXXXXXXXXX03",
      "name": "RRE-Blue River warehouse sensors",
      "stage": "proposal",
      "estRevenue": 60000000,
      "account": {
        "name": "",
        "id": "ACCXXXXXXXXXX02",
        "objectSlug": "account"
      }
    }
  ]
}

curl -s 'http://127.0.0.1:3100/api/v1/ts-projects/records_demo/opportunities/{OPPORTUNITY_ID}' | jq

{
  "system": {
    "createdAt": 1790659225126,
    "createdBy": {
      "name": "",
      "id": "PERXXXXXXXXXXXX"
    },
    "updatedAt": 1790659923000
  },
  "id": "OPPXXXXXXXXXX01",
  "fields": {
    "stage": "proposal",
    "name": "RRE-Acme POS rollout",
    "est_revenue": 120000000,
    "account": {
      "name": "",
      "id": "ACCXXXXXXXXXX01",
      "objectSlug": "account"
    }
  }
}

  const page = await opportunities.records.list({
    fields: OPPORTUNITY_FIELDS,
    expandLookups: { account: ["industry"] },
    where: opportunities.fields.stage.in(OPEN_STAGES),
    orderBy: [opportunities.fields.est_revenue.desc()],
    limit: 3,
  });

curl -s 'http://127.0.0.1:3100/api/v1/ts-projects/records_demo/opportunities' | jq '.opportunities[0]'

{
  "id": "OPPXXXXXXXXXX01",
  "name": "RRE-Acme POS rollout",
  "stage": "proposal",
  "estRevenue": 120000000,
  "account": {
    "name": "RRE-Acme Retail",
    "id": "ACCXXXXXXXXXX01",
    "objectSlug": "account",
    "fields": {
      "industry": "retail"
    }
  }
}

router.get("/opportunities/:opportunityId/summary", async ({ data, org, request, response }) => {
  const opportunityId = request.params.opportunityId ?? "";
  if (!ID_PATTERN.test(opportunityId)) {
    return response.json({ error: "A valid opportunity id is required" }, { status: 400 });
  }
  const opportunity = await data.object("opportunity").records.get(opportunityId, {
    fields: ["name", "account", "owner"],
    expandLookups: true,
  });
  if (opportunity === null) {
    return response.json({ error: "Opportunity not found" }, { status: 404 });
  }
  const { account, owner } = opportunity.fields;
  const createdBy = opportunity.system.createdBy;
  const creator = createdBy === undefined
    ? null
    : await org.personnel.get(createdBy.id, { withDisplay: true });
  return {
    name: opportunity.fields.name,
    account: {
      name: account.name,
      industry: account.fields?.industry ?? null,
      fieldsRead: Object.keys(account.fields ?? {}).length,
    },
    owner: owner?.name ?? null,
    createdBy: {
      name: createdBy?.name ?? null,
      displayName: creator?.display?.name ?? null,
    },
  };
});

curl -s 'http://127.0.0.1:3100/api/v1/ts-projects/records_demo/opportunities/{OPPORTUNITY_ID}/summary' | jq

{
  "name": "RRE-Acme POS rollout",
  "account": {
    "name": "RRE-Acme Retail",
    "industry": "retail",
    "fieldsRead": 26
  },
  "owner": "PERSONNEL-0000000002-13/09/2026",
  "createdBy": {
    "name": "PERSONNEL-0000000002-13/09/2026",
    "displayName": "An Nguyen"
  }
}

import { createRouter, ValidationError, type ResponseApi } from "@cogover/sdk";

// Answers HTTP 400 with the reason when Cogover refuses the options of a call.
async function explainRefusal<T>(response: ResponseApi, run: () => Promise<T>) {
  try {
    return await run();
  } catch (error) {
    if (error instanceof ValidationError) {
      return response.json({ error: error.message }, { status: 400 });
    }
    throw error;
  }
}
 
router.get("/pipeline", async ({ data }) => {
  const opportunities = data.object("opportunity");
  const result = await opportunities.records.aggregate({
    where: opportunities.fields.stage.in(OPEN_STAGES),
    metrics: {
      opportunities: { count: "id" },
      revenue: { sum: "est_revenue" },
      averageRevenue: { avg: "est_revenue" },
      largestRevenue: { max: "est_revenue" },
    },
  });
  return result.values;
});
 
router.get("/pipeline/by-stage", ({ data, response }) => explainRefusal(response, async () => {
  const result = await data.object("opportunity").records.aggregate({
    groupBy: ["stage"],
    metrics: {
      opportunities: { count: "id" },
      revenue: { sum: "est_revenue" },
      accounts: { countDistinct: "account" },
    },
  });
  return {
    stages: result.groups.map(group => ({ stage: group.key.stage, ...group.values })),
    truncated: result.truncated,
  };
}));
 
router.get("/pipeline/top-accounts", ({ data, response }) => explainRefusal(response, async () => {
  const opportunities = data.object("opportunity");
  const result = await opportunities.records.aggregate({
    where: opportunities.fields.stage.in(OPEN_STAGES),
    groupBy: ["account"],
    metrics: {
      opportunities: { count: "id" },
      revenue: { sum: "est_revenue" },
    },
    limit: 2,
  });
  const accountIds = result.groups.map(group => group.key.account);
  const { records } = await data.object("account").records.getMany(accountIds, {
    fields: ["name"],
  });
  const nameById = new Map(records.map(record => [record.id, record.fields.name]));
  return {
    accounts: result.groups.map(group => ({
      id: group.key.account,
      name: nameById.get(group.key.account) ?? null,
      ...group.values,
    })),
    truncated: result.truncated,
  };
}));

curl -s 'http://127.0.0.1:3100/api/v1/ts-projects/records_demo/pipeline' | jq

{
  "revenue": 355000000,
  "averageRevenue": 39444444.44444445,
  "largestRevenue": 120000000,
  "opportunities": 9
}

curl -s -i 'http://127.0.0.1:3100/api/v1/ts-projects/records_demo/pipeline/by-stage'

{"error":"aggregate with groupBy is not supported for the default identity of this invocation, which reads as a delegated user; use asSystem()"}

npm run build
cogover-dev publish

Published version 8 (TSVXXXXXXXXXXXX) is READY.
Next: cogover-dev activate TSVXXXXXXXXXXXX

cogover-dev activate {VERSION_ID}

Activated version TSVXXXXXXXXXXXX.

cogover-dev auth session --format curl --output .cogover-session.curl
curl -s --config .cogover-session.curl \
  'https://{WORKSPACE_DOMAIN}/api/v1/ts-projects/records_demo/pipeline/by-stage' \
  -H 'x-req-type: 9' -H 'x-req-service: 3' | jq

{
  "stages": [
    {
      "stage": "proposal",
      "revenue": 230000000,
      "accounts": 4,
      "opportunities": 4
    },
    {
      "stage": "needs_analysis",
      "revenue": 45000000,
      "accounts": 3,
      "opportunities": 3
    },
    {
      "stage": "negotiation",
      "revenue": 80000000,
      "accounts": 2,
      "opportunities": 2
    },
    {
      "stage": "closed_lost",
      "revenue": 30000000,
      "accounts": 1,
      "opportunities": 1
    },
    {
      "stage": "closed_won",
      "revenue": 150000000,
      "accounts": 1,
      "opportunities": 1
    }
  ],
  "truncated": false
}

curl -s --config .cogover-session.curl \
  'https://{WORKSPACE_DOMAIN}/api/v1/ts-projects/records_demo/pipeline/top-accounts' \
  -H 'x-req-type: 9' -H 'x-req-service: 3' | jq

{
  "accounts": [
    {
      "id": "ACCXXXXXXXXXX01",
      "name": "RRE-Acme Retail",
      "revenue": 200000000,
      "opportunities": 2
    },
    {
      "id": "ACCXXXXXXXXXX02",
      "name": "RRE-Blue River Logistics",
      "revenue": 105000000,
      "opportunities": 2
    }
  ],
  "truncated": true
}

curl -s --config .cogover-session.curl \
  'https://{WORKSPACE_DOMAIN}/api/v1/ts-projects/records_demo/pipeline' \
  -H 'x-req-type: 9' -H 'x-req-service: 3' | jq

{
  "revenue": 355000000,
  "averageRevenue": 39444444.44444445,
  "largestRevenue": 120000000,
  "opportunities": 9
}

rm -f .cogover-session.curl

cogover-dev logout --profile records_demo
cogover-dev auth logout

import { defineTrigger } from "@cogover/sdk";
 
export const triggers = [
  defineTrigger({
    key: "revenue_within_account",
    object: "opportunity",
    timing: "beforeChange",
    operations: ["create", "update"],
    fields: ["account", "est_revenue"],
    changedFields: ["account", "est_revenue"],
  }, async ({ records, data }) => {
    const accountIds = records.flatMap(record => {
      const account = record.new.account;
      return typeof account === "object" && account !== null ? [account.id] : [];
    });
    const { records: accounts } = await data.object("account").records.getMany(accountIds, {
      fields: ["annual_revenue"],
    });
    const annualRevenue = new Map(accounts.map(account => [account.id, account.fields.annual_revenue]));
    for (const record of records) {
      const { account, est_revenue: estRevenue } = record.new;
      if (typeof account !== "object" || account === null || typeof estRevenue !== "number") continue;
      const limit = annualRevenue.get(account.id);
      if (typeof limit === "number" && estRevenue > limit) {
        record.addError("est_revenue", "ABOVE_ACCOUNT_REVENUE",
          `The estimated revenue is above the annual revenue of ${account.name}.`);
      }
    }
  }),
];

import { createRouter, ValidationError, type ResponseApi } from "@cogover/sdk";
 
const router = createRouter();
const ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
const OPEN_STAGES = ["needs_analysis", "proposal", "negotiation"] as const;
const OPPORTUNITY_FIELDS = ["name", "stage", "est_revenue", "account"] as const;
 
router.get("/opportunities", async ({ data }) => {
  const opportunities = data.object("opportunity");
  const page = await opportunities.records.list({
    fields: OPPORTUNITY_FIELDS,
    expandLookups: { account: ["industry"] },
    where: opportunities.fields.stage.in(OPEN_STAGES),
    orderBy: [opportunities.fields.est_revenue.desc()],
    limit: 3,
  });
  return {
    total: page.total,
    opportunities: page.items.map(item => ({
      id: item.id,
      name: item.fields.name,
      stage: item.fields.stage,
      estRevenue: item.fields.est_revenue,
      account: item.fields.account,
    })),
  };
});
 
router.get("/opportunities/:opportunityId", async ({ data, request, response }) => {
  const opportunityId = request.params.opportunityId ?? "";
  if (!ID_PATTERN.test(opportunityId)) {
    return response.json({ error: "A valid opportunity id is required" }, { status: 400 });
  }
  const opportunity = await data.object("opportunity").records.get(opportunityId, {
    fields: OPPORTUNITY_FIELDS,
  });
  if (opportunity === null) {
    return response.json({ error: "Opportunity not found" }, { status: 404 });
  }
  return opportunity;
});
 
router.get("/opportunities/:opportunityId/summary", async ({ data, org, request, response }) => {
  const opportunityId = request.params.opportunityId ?? "";
  if (!ID_PATTERN.test(opportunityId)) {
    return response.json({ error: "A valid opportunity id is required" }, { status: 400 });
  }
  const opportunity = await data.object("opportunity").records.get(opportunityId, {
    fields: ["name", "account", "owner"],
    expandLookups: true,
  });
  if (opportunity === null) {
    return response.json({ error: "Opportunity not found" }, { status: 404 });
  }
  const { account, owner } = opportunity.fields;
  const createdBy = opportunity.system.createdBy;
  const creator = createdBy === undefined
    ? null
    : await org.personnel.get(createdBy.id, { withDisplay: true });
  return {
    name: opportunity.fields.name,
    account: {
      name: account.name,
      industry: account.fields?.industry ?? null,
      fieldsRead: Object.keys(account.fields ?? {}).length,
    },
    owner: owner?.name ?? null,
    createdBy: {
      name: createdBy?.name ?? null,
      displayName: creator?.display?.name ?? null,
    },
  };
});
 
// Answers HTTP 400 with the reason when Cogover refuses the options of a call.
async function explainRefusal<T>(response: ResponseApi, run: () => Promise<T>) {
  try {
    return await run();
  } catch (error) {
    if (error instanceof ValidationError) {
      return response.json({ error: error.message }, { status: 400 });
    }
    throw error;
  }
}
 
router.get("/pipeline", async ({ data }) => {
  const opportunities = data.object("opportunity");
  const result = await opportunities.records.aggregate({
    where: opportunities.fields.stage.in(OPEN_STAGES),
    metrics: {
      opportunities: { count: "id" },
      revenue: { sum: "est_revenue" },
      averageRevenue: { avg: "est_revenue" },
      largestRevenue: { max: "est_revenue" },
    },
  });
  return result.values;
});
 
router.get("/pipeline/by-stage", ({ data, response }) => explainRefusal(response, async () => {
  const result = await data.object("opportunity").records.aggregate({
    groupBy: ["stage"],
    metrics: {
      opportunities: { count: "id" },
      revenue: { sum: "est_revenue" },
      accounts: { countDistinct: "account" },
    },
  });
  return {
    stages: result.groups.map(group => ({ stage: group.key.stage, ...group.values })),
    truncated: result.truncated,
  };
}));
 
router.get("/pipeline/top-accounts", ({ data, response }) => explainRefusal(response, async () => {
  const opportunities = data.object("opportunity");
  const result = await opportunities.records.aggregate({
    where: opportunities.fields.stage.in(OPEN_STAGES),
    groupBy: ["account"],
    metrics: {
      opportunities: { count: "id" },
      revenue: { sum: "est_revenue" },
    },
    limit: 2,
  });
  const accountIds = result.groups.map(group => group.key.account);
  const { records } = await data.object("account").records.getMany(accountIds, {
    fields: ["name"],
  });
  const nameById = new Map(records.map(record => [record.id, record.fields.name]));
  return {
    accounts: result.groups.map(group => ({
      id: group.key.account,
      name: nameById.get(group.key.account) ?? null,
      ...group.values,
    })),
    truncated: result.truncated,
  };
}));
 
export default router.toHandler();