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

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

COGOVER_API_KEY={WORKSPACE_API_KEY}

import {
  CogoverApiError, createRouter, NotFoundError, PermissionDeniedError, RateLimitError, ValidationError,
  type ResponseApi,
} from "@cogover/sdk";
 
const router = createRouter();
const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
 
router.post("/notify", async ({ request, invocation, notifications, response }) => {
  const body = (request.body ?? {}) as { to?: unknown; title?: unknown; content?: unknown; key?: unknown };
  const me = invocation.user?.membership.personnelId;
  const to = body.to ?? (me === undefined ? [] : [me]);
  if (!Array.isArray(to) || to.length === 0 || !to.every((id): id is string => typeof id === "string")) {
    return response.json({ error: "to must list at least one personnel ID" }, { status: 400 });
  }
  if (typeof body.title !== "string" || typeof body.content !== "string") {
    return response.json({ error: "title and content are required" }, { status: 400 });
  }
  if (body.key !== undefined && (typeof body.key !== "string" || !KEY_PATTERN.test(body.key))) {
    return response.json({ error: "key must be 1 to 128 letters, digits, '.', '_', ':' or '-'" }, { status: 400 });
  }
 
  try {
    return await notifications.send({
      to,
      title: body.title,
      content: body.content,
      ...(typeof body.key === "string" ? { idempotencyKey: body.key } : {}),
    });
  } catch (error) {
    return failure(error, response);
  }
});
 
function failure(error: unknown, response: ResponseApi) {
  if (error instanceof ValidationError) {
    return response.json({ error: error.message }, { status: 400 });
  }
  if (error instanceof NotFoundError) {
    return response.json({ error: "Not found", resource: error.resource, id: error.resourceId }, { status: 404 });
  }
  if (error instanceof PermissionDeniedError) {
    const reason = (error.details as { reason?: unknown } | undefined)?.reason ?? null;
    return response.json({ error: "Not allowed", reason }, { status: 403 });
  }
  if (error instanceof RateLimitError) {
    // details.budget có giá trị khi lần thực thi này đã dùng hết một ngân sách: gửi lại đúng request đó không giúp được gì.
    const budget = (error.details as { budget?: unknown } | undefined)?.budget;
    return budget === undefined
      ? response.json({ error: "The hourly limit was reached; try again later" }, { status: 429 })
      : response.json({ error: "This request used up a budget of its execution", budget }, { status: 429 });
  }
  if (error instanceof CogoverApiError && error.code === "DUPLICATE_IN_PROGRESS") {
    return response.json({ error: "The same message is still being sent; retry shortly" }, { status: 409 });
  }
  throw error;
}
 
export default router.toHandler();

cogover-dev login --profile notify_demo
cogover-dev doctor --profile notify_demo
COGOVER_LOCAL_PORT=3100 cogover-dev run --profile notify_demo -- npm run dev

curl -s -X POST 'http://127.0.0.1:3100/api/v1/ts-projects/notify_demo/notify' \
  -H 'Content-Type: application/json' \
  --data '{"title":"Hello from notify_demo","content":"This notification was sent by a Custom Backend Module."}' | jq

{
  "requestId": "NTFQ7K2M9X4B1C8D5E6",
  "notified": 1,
  "skippedPersonnelIds": [],
  "duplicate": false
}

curl -s -X POST 'http://127.0.0.1:3100/api/v1/ts-projects/notify_demo/notify' \
  -H 'Content-Type: application/json' \
  --data '{"title":"Order SO-1001 shipped","content":"The order left the warehouse.","key":"order-shipped-SO-1001"}' | jq '{requestId, duplicate}'

curl -s -i -X POST 'http://127.0.0.1:3100/api/v1/ts-projects/notify_demo/notify' \
  -H 'Content-Type: application/json' \
  --data '{"to":["PERUNKNOWN00000"],"title":"Hello","content":"Nobody should get this."}'

curl -s -i -X POST 'http://127.0.0.1:3100/api/v1/ts-projects/notify_demo/notify' \
  -H 'Content-Type: application/json' --data '{}'

cogover-dev auth session --format curl --output .cogover-session.curl

DEMO_ORIGIN='https://{WORKSPACE_DOMAIN}'
DEMO_PROJECT_ID='{PROJECT_ID}'

curl -s --config .cogover-session.curl -X POST \
  "$DEMO_ORIGIN/api/v1/ts-projects/$DEMO_PROJECT_ID/identity-policy/get" \
  -H 'x-req-type: 9' -H 'x-req-service: 4' \
  -H 'Content-Type: application/json' --data '{}' | jq -c '.'

curl -s --config .cogover-session.curl -X POST \
  "$DEMO_ORIGIN/api/v1/ts-projects/$DEMO_PROJECT_ID/identity-policy/get" \
  -H 'x-req-type: 9' -H 'x-req-service: 4' \
  -H 'Content-Type: application/json' --data '{}' \
  | jq '.policy | with_entries(select(.value != null))
        | .email = {"workspaceMailboxIds": [], "allowActorMailbox": true}' > email-policy.json

cat > email-policy.json <<'EOF'
{
  "schemaVersion": 2,
  "callerPersonnelIds": { "mode": "ALL", "personnelIds": [] },
  "allowInternalSystem": false,
  "email": { "workspaceMailboxIds": [], "allowActorMailbox": true }
}
EOF

curl -s --config .cogover-session.curl -X POST \
  "$DEMO_ORIGIN/api/v1/ts-projects/$DEMO_PROJECT_ID/identity-policy" \
  -H 'x-req-type: 9' -H 'x-req-service: 4' \
  -H 'Content-Type: application/json' --data @email-policy.json | jq '.status // .'
curl -s --config .cogover-session.curl -X POST \
  "$DEMO_ORIGIN/api/v1/ts-projects/$DEMO_PROJECT_ID/identity-policy/activate" \
  -H 'x-req-type: 9' -H 'x-req-service: 4' \
  -H 'Content-Type: application/json' --data '{}' | jq '.status // .'

import {
  CogoverApiError, createRouter, NotFoundError, PermissionDeniedError, RateLimitError, ValidationError,
  type EmailSender, type ResponseApi,
} from "@cogover/sdk";
 
const router = createRouter();
const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
const MAILBOX_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
 
router.post("/notify", async ({ request, invocation, notifications, response }) => {
  const body = (request.body ?? {}) as { to?: unknown; title?: unknown; content?: unknown; key?: unknown };
  const me = invocation.user?.membership.personnelId;
  const to = body.to ?? (me === undefined ? [] : [me]);
  if (!Array.isArray(to) || to.length === 0 || !to.every((id): id is string => typeof id === "string")) {
    return response.json({ error: "to must list at least one personnel ID" }, { status: 400 });
  }
  if (typeof body.title !== "string" || typeof body.content !== "string") {
    return response.json({ error: "title and content are required" }, { status: 400 });
  }
  if (body.key !== undefined && (typeof body.key !== "string" || !KEY_PATTERN.test(body.key))) {
    return response.json({ error: "key must be 1 to 128 letters, digits, '.', '_', ':' or '-'" }, { status: 400 });
  }
 
  try {
    return await notifications.send({
      to,
      title: body.title,
      content: body.content,
      ...(typeof body.key === "string" ? { idempotencyKey: body.key } : {}),
    });
  } catch (error) {
    return failure(error, response);
  }
});
 
router.get("/email/senders", async ({ email }) => {
  return { senders: await email.senders() };
});
 
router.post("/email/send", async ({ request, email, response }) => {
  const body = (request.body ?? {}) as {
    mailboxId?: unknown; to?: unknown; subject?: unknown; text?: unknown; key?: unknown;
  };
  const from = sender(body.mailboxId);
  if (from === null) {
    return response.json({ error: "mailboxId must be a mailbox ID" }, { status: 400 });
  }
  if (typeof body.to !== "string" || typeof body.subject !== "string" || typeof body.text !== "string") {
    return response.json({ error: "to, subject and text are required" }, { status: 400 });
  }
  if (body.key !== undefined && (typeof body.key !== "string" || !KEY_PATTERN.test(body.key))) {
    return response.json({ error: "key must be 1 to 128 letters, digits, '.', '_', ':' or '-'" }, { status: 400 });
  }
 
  try {
    return await email.send({
      from,
      to: [body.to],
      subject: body.subject,
      text: body.text,
      ...(typeof body.key === "string" ? { idempotencyKey: body.key } : {}),
    });
  } catch (error) {
    return failure(error, response);
  }
});
 
router.post("/email/records/:object/:recordId", async ({ request, email, response }) => {
  const body = (request.body ?? {}) as { mailboxId?: unknown; emailField?: unknown; subject?: unknown; html?: unknown };
  const from = sender(body.mailboxId);
  if (from === null) {
    return response.json({ error: "mailboxId must be a mailbox ID" }, { status: 400 });
  }
  if (typeof body.emailField !== "string" || typeof body.subject !== "string" || typeof body.html !== "string") {
    return response.json({ error: "emailField, subject and html are required" }, { status: 400 });
  }
 
  try {
    return await email.send({
      from,
      subject: body.subject,
      html: body.html,
      record: { object: request.params.object ?? "", recordId: request.params.recordId ?? "" },
      recordEmailFields: [body.emailField],
    });
  } catch (error) {
    return failure(error, response);
  }
});
 
// Without a mailbox ID, send from the caller's own mailbox.
function sender(mailboxId: unknown): EmailSender | null {
  if (mailboxId === undefined) return "actor";
  return typeof mailboxId === "string" && MAILBOX_PATTERN.test(mailboxId) ? { mailbox: mailboxId } : null;
}
 
function failure(error: unknown, response: ResponseApi) {
  if (error instanceof ValidationError) {
    return response.json({ error: error.message }, { status: 400 });
  }
  if (error instanceof NotFoundError) {
    return response.json({ error: "Not found", resource: error.resource, id: error.resourceId }, { status: 404 });
  }
  if (error instanceof PermissionDeniedError) {
    const reason = (error.details as { reason?: unknown } | undefined)?.reason ?? null;
    return response.json({ error: "Not allowed", reason }, { status: 403 });
  }
  if (error instanceof RateLimitError) {
    // details.budget có giá trị khi lần thực thi này đã dùng hết một ngân sách: gửi lại đúng request đó không giúp được gì.
    const budget = (error.details as { budget?: unknown } | undefined)?.budget;
    return budget === undefined
      ? response.json({ error: "The hourly limit was reached; try again later" }, { status: 429 })
      : response.json({ error: "This request used up a budget of its execution", budget }, { status: 429 });
  }
  if (error instanceof CogoverApiError && error.code === "DUPLICATE_IN_PROGRESS") {
    return response.json({ error: "The same message is still being sent; retry shortly" }, { status: 409 });
  }
  throw error;
}
 
export default router.toHandler();

COGOVER_LOCAL_PORT=3100 cogover-dev run --profile notify_demo -- npm run dev

curl -s 'http://127.0.0.1:3100/api/v1/ts-projects/notify_demo/email/senders' | jq

{
  "senders": [
    {
      "id": "EAq7K2m9X4b1C",
      "kind": "actor",
      "email": "giang.ho@example.com",
      "displayName": "Giang Ho - Sales"
    }
  ]
}

curl -s -X POST 'http://127.0.0.1:3100/api/v1/ts-projects/notify_demo/email/send' \
  -H 'Content-Type: application/json' \
  --data '{"to":"{YOUR_EMAIL}","subject":"Hello from notify_demo","text":"Sent with email.send.","key":"hello-email-1"}' | jq

{
  "requestId": "EMLQ7K2M9X4B1C8D5E6",
  "delivery": "direct",
  "recipients": 1,
  "duplicate": false
}

curl -s -i -X POST 'http://127.0.0.1:3100/api/v1/ts-projects/notify_demo/email/send' \
  -H 'Content-Type: application/json' \
  --data '{"mailboxId":"NOTGRANTED","to":"{YOUR_EMAIL}","subject":"Hello","text":"This is refused."}'

curl -s -X POST 'http://127.0.0.1:3100/api/v1/ts-projects/notify_demo/email/records/{OBJECT_SLUG}/{RECORD_ID}' \
  -H 'Content-Type: application/json' \
  --data '{"emailField":"{EMAIL_FIELD}","subject":"Your documents","html":"<p>Hello,</p><p>This email is logged on your record.</p>"}' | jq

{
  "requestId": "EMLR3T8W1Z5Y2V6U9S4",
  "delivery": "activity",
  "recipients": 0,
  "duplicate": false
}

npm run build
cogover-dev publish

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

curl -s --config .cogover-session.curl -X POST \
  "$DEMO_ORIGIN/api/v1/ts-projects/$DEMO_PROJECT_ID/versions/{VERSION_ID}/identity-policy/approve" \
  -H 'x-req-type: 9' -H 'x-req-service: 4' \
  -H 'Content-Type: application/json' --data '{}' | jq '.status // .'

cogover-dev activate {VERSION_ID}

curl -s --config .cogover-session.curl \
  "$DEMO_ORIGIN/api/v1/ts-projects/notify_demo/email/senders" \
  -H 'x-req-type: 9' -H 'x-req-service: 3' | jq '.'
curl -s --config .cogover-session.curl -X POST \
  "$DEMO_ORIGIN/api/v1/ts-projects/notify_demo/notify" \
  -H 'x-req-type: 9' -H 'x-req-service: 3' \
  -H 'Content-Type: application/json' \
  --data '{"title":"Hello from the published version","content":"notify_demo is live."}' | jq '.'

rm -f .cogover-session.curl email-policy.json

// In an after-change trigger: the same change of the same record always gives the same key.
idempotencyKey: `order-shipped:${trigger.changeId}:${record.id}`,
// In a background job: the same run always gives the same key.
idempotencyKey: `weekly-report:${job.id}`,