Skip to content

Job application tracker and AI-powered job search assistant. Helps job seekers manage their search journey with AI resume review, job matching, task logging, and application analytics, all while keeping your data private.

feat(contacts): add a Companies contacts count, contact-aware delete guards and the contacts help page

Khuram Niaz49880c8d0454
diff --git a/__tests__/CompaniesContainer.spec.tsx b/__tests__/CompaniesContainer.spec.tsx
index 656670d..449e0e9 100644
--- a/__tests__/CompaniesContainer.spec.tsx
+++ b/__tests__/CompaniesContainer.spec.tsx
@@ -1,5 +1,5 @@
import CompaniesContainer from "@/components/admin/CompaniesContainer";
-import { screen, render, waitFor, act } from "@testing-library/react";
+import { screen, render, waitFor, act, within } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { getCompanyList, getCompanyById } from "@/actions/company.actions";
import { searchAtsCompanies } from "@/actions/atsCompany.actions";
@@ -45,7 +45,15 @@ global.IntersectionObserver = class IntersectionObserver {
describe("CompaniesContainer Search Functionality", () => {
const mockCompanies = [
- { id: "1", label: "Amazon", value: "amazon", createdBy: "user-1" },
+ {
+ id: "1",
+ label: "Amazon",
+ value: "amazon",
+ createdBy: "user-1",
+ // Job tallies are left out on purpose: a non-zero one renders next/link,
+ // whose own IntersectionObserver would shadow the sentinel's here.
+ _count: { contacts: 3 },
+ },
{ id: "2", label: "Google", value: "google", createdBy: "user-1" },
];
@@ -407,4 +415,22 @@ describe("CompaniesContainer Search Functionality", () => {
);
});
});
+ describe("Contacts count", () => {
+ it("shows how many contacts work at each company", async () => {
+ (getCompanyList as any).mockResolvedValue({
+ data: mockCompanies,
+ total: 2,
+ });
+
+ render(<CompaniesContainer />);
+
+ await waitFor(() =>
+ expect(
+ screen.getByRole("columnheader", { name: "Contacts" })
+ ).toBeInTheDocument()
+ );
+ const row = screen.getByRole("row", { name: /Amazon/ });
+ expect(within(row).getByText("3")).toBeInTheDocument();
+ });
+ });
});
diff --git a/__tests__/company.actions.spec.ts b/__tests__/company.actions.spec.ts
index 4d7c76c..16e42be 100644
--- a/__tests__/company.actions.spec.ts
+++ b/__tests__/company.actions.spec.ts
@@ -27,6 +27,9 @@ vi.mock("@prisma/client", () => {
workExperience: {
count: vi.fn(),
},
+ contact: {
+ count: vi.fn(),
+ },
job: {
count: vi.fn(),
groupBy: vi.fn(),
@@ -139,6 +142,11 @@ describe("Company Actions", () => {
applied: true,
},
},
+ contacts: {
+ where: {
+ createdBy: mockUser.id,
+ },
+ },
},
},
},
@@ -252,6 +260,11 @@ describe("Company Actions", () => {
applied: true,
},
},
+ contacts: {
+ where: {
+ createdBy: mockUser.id,
+ },
+ },
},
},
},
@@ -868,6 +881,10 @@ describe("Company Actions", () => {
});
describe("deleteCompanyById", () => {
+ beforeEach(() => {
+ (prisma.contact.count as any).mockResolvedValue(0);
+ });
+
it("should delete a company successfully", async () => {
(getCurrentUser as any).mockResolvedValue(mockUser);
(prisma.workExperience.count as any).mockResolvedValue(0);
@@ -941,6 +958,25 @@ describe("Company Actions", () => {
expect(prisma.company.delete).not.toHaveBeenCalled();
});
+ it("refuses to delete a company that a contact points at, either way", async () => {
+ (getCurrentUser as any).mockResolvedValue(mockUser);
+ (prisma.workExperience.count as any).mockResolvedValue(0);
+ (prisma.job.count as any).mockResolvedValue(0);
+ (prisma.contact.count as any).mockResolvedValue(2);
+
+ const result = await deleteCompanyById("co1");
+
+ expect(prisma.contact.count).toHaveBeenCalledWith({
+ where: {
+ createdBy: mockUser.id,
+ OR: [{ companyId: "co1" }, { workedAtCompanyId: "co1" }],
+ },
+ });
+ expect(result.success).toBe(false);
+ expect(result.message).toContain("2");
+ expect(prisma.company.delete).not.toHaveBeenCalled();
+ });
+
it("should handle unexpected errors", async () => {
(getCurrentUser as any).mockResolvedValue(mockUser);
(prisma.workExperience.count as any).mockResolvedValue(0);
diff --git a/__tests__/jobLocation.actions.spec.ts b/__tests__/jobLocation.actions.spec.ts
index 3ff8b6e..5838076 100644
--- a/__tests__/jobLocation.actions.spec.ts
+++ b/__tests__/jobLocation.actions.spec.ts
@@ -21,6 +21,9 @@ vi.mock("@prisma/client", () => {
education: {
count: vi.fn(),
},
+ contact: {
+ count: vi.fn(),
+ },
job: {
count: vi.fn(),
groupBy: vi.fn(),
@@ -211,6 +214,10 @@ describe("Job Location Actions", () => {
});
describe("deleteJobLocationById", () => {
+ beforeEach(() => {
+ (prisma.contact.count as any).mockResolvedValue(0);
+ });
+
it("should delete a location successfully", async () => {
(getCurrentUser as any).mockResolvedValue(mockUser);
(prisma.workExperience.count as any).mockResolvedValue(0);
@@ -283,6 +290,22 @@ describe("Job Location Actions", () => {
expect(prisma.location.delete).not.toHaveBeenCalled();
});
+ it("refuses to delete a location a contact points at", async () => {
+ (getCurrentUser as any).mockResolvedValue(mockUser);
+ (prisma.workExperience.count as any).mockResolvedValue(0);
+ (prisma.education.count as any).mockResolvedValue(0);
+ (prisma.job.count as any).mockResolvedValue(0);
+ (prisma.contact.count as any).mockResolvedValue(1);
+
+ const result = await deleteJobLocationById("loc-1");
+
+ expect(prisma.contact.count).toHaveBeenCalledWith({
+ where: { locationId: "loc-1", createdBy: mockUser.id },
+ });
+ expect(result.success).toBe(false);
+ expect(prisma.location.delete).not.toHaveBeenCalled();
+ });
+
it("should handle unexpected errors", async () => {
(getCurrentUser as any).mockResolvedValue(mockUser);
(prisma.workExperience.count as any).mockResolvedValue(0);
diff --git a/__tests__/referenceList.spec.ts b/__tests__/referenceList.spec.ts
index 1a31703..b61b172 100644
--- a/__tests__/referenceList.spec.ts
+++ b/__tests__/referenceList.spec.ts
@@ -346,4 +346,76 @@ describe("getReferenceEntityList", () => {
expect.objectContaining({ orderBy })
);
});
-});
+ describe("relationCounts", () => {
+ const base = {
+ userId,
+ fkField: "companyId",
+ appliedRelation: "jobsApplied",
+ page: 1,
+ limit: 10,
+ countBy: "applied",
+ };
+
+ it("merges a relation count into the same _count.select, costing no extra query", async () => {
+ const model = makeModel([]);
+
+ await getReferenceEntityList({
+ ...base,
+ model,
+ relationCounts: [
+ { key: "contacts", relation: "contacts", where: { createdBy: "u1" } },
+ ],
+ });
+
+ const select = model.findMany.mock.calls[0][0].select;
+ expect(select._count.select).toEqual({
+ jobsApplied: { where: { applied: true } },
+ contacts: { where: { createdBy: "u1" } },
+ });
+ });
+
+ it("counts the whole relation when no where is given", async () => {
+ const model = makeModel([]);
+
+ await getReferenceEntityList({
+ ...base,
+ model,
+ relationCounts: [{ key: "contacts", relation: "contacts" }],
+ });
+
+ expect(
+ model.findMany.mock.calls[0][0].select._count.select.contacts
+ ).toBe(true);
+ });
+
+ it("renames the relation to the requested key on the returned rows", async () => {
+ const model = makeModel([
+ {
+ id: "c1",
+ label: "Shopify",
+ value: "shopify",
+ _count: { jobsApplied: 2, formerColleagues: 4 },
+ },
+ ]);
+
+ const { data } = await getReferenceEntityList({
+ ...base,
+ model,
+ relationCounts: [{ key: "exColleagues", relation: "formerColleagues" }],
+ });
+
+ expect(data[0]._count.exColleagues).toBe(4);
+ expect(data[0]._count).not.toHaveProperty("formerColleagues");
+ });
+
+ it("leaves the query untouched when no relationCounts are given", async () => {
+ const model = makeModel([]);
+
+ await getReferenceEntityList({ ...base, model });
+
+ expect(model.findMany.mock.calls[0][0].select._count.select).toEqual({
+ jobsApplied: { where: { applied: true } },
+ });
+ });
+ });
+});
\ No newline at end of file
diff --git a/src/actions/company/mutations.ts b/src/actions/company/mutations.ts
index ded2db2..df4e126 100644
--- a/src/actions/company/mutations.ts
+++ b/src/actions/company/mutations.ts
@@ -204,6 +204,21 @@ export const deleteCompanyById = async (
);
}
+ // Contact.companyId and .workedAtCompanyId are optional relations, whose
+ // Prisma default is SetNull — deleting would silently blank the employer
+ // rather than fail. This guard is the only thing stopping it.
+ const contacts = await prisma.contact.count({
+ where: {
+ createdBy: user.id,
+ OR: [{ companyId }, { workedAtCompanyId: companyId }],
+ },
+ });
+ if (contacts > 0) {
+ throw new Error(
+ `Company cannot be deleted due to ${contacts} associated contact${contacts === 1 ? "" : "s"}! `,
+ );
+ }
+
const res = await prisma.company.delete({
where: {
id: companyId,
diff --git a/src/actions/company/queries.ts b/src/actions/company/queries.ts
index 7a90511..316190f 100644
--- a/src/actions/company/queries.ts
+++ b/src/actions/company/queries.ts
@@ -33,6 +33,9 @@ export const getCompanyList = async (
extraCounts: [
{ key: "jobsRejected", where: { Status: { value: "rejected" } } },
],
+ relationCounts: [
+ { key: "contacts", relation: "contacts", where: { createdBy: user.id } },
+ ],
// A watched row sits at applied-count 0, so the default sort would bury
// whatever was just watched; most-recent-first is what the scope is for.
...(watchlist
diff --git a/src/actions/jobLocation.actions.ts b/src/actions/jobLocation.actions.ts
index 8bcb369..3b276ed 100644
--- a/src/actions/jobLocation.actions.ts
+++ b/src/actions/jobLocation.actions.ts
@@ -86,6 +86,17 @@ export const deleteJobLocationById = async (
);
}
+ // Optional relation, so the Prisma default is SetNull; same reasoning as
+ // the company guard — nothing at the database level blocks this.
+ const contacts = await prisma.contact.count({
+ where: { locationId, createdBy: user.id },
+ });
+ if (contacts > 0) {
+ throw new Error(
+ `Location cannot be deleted due to ${contacts} associated contact${contacts === 1 ? "" : "s"}! `
+ );
+ }
+
const res = await prisma.location.delete({
where: {
id: locationId,
diff --git a/src/actions/referenceList.ts b/src/actions/referenceList.ts
index 9e6bb37..8cee6ce 100644
--- a/src/actions/referenceList.ts
+++ b/src/actions/referenceList.ts
@@ -13,6 +13,14 @@ export type ReferenceExtraCount = {
where: Record<string, any>;
};
+// Merged into the inline _count.select, unlike extraCounts — which is a
+// per-entry prisma.job.groupBy and can therefore only ever count jobs.
+export type ReferenceRelationCount = {
+ key: string;
+ relation: string;
+ where?: Record<string, any>;
+};
+
export type ReferenceListParams = {
model: ReferenceListDelegate;
userId: string;
@@ -20,6 +28,7 @@ export type ReferenceListParams = {
appliedRelation: string;
extraSelect?: Record<string, true>;
extraCounts?: ReferenceExtraCount[];
+ relationCounts?: ReferenceRelationCount[];
extraWhere?: Record<string, any>;
searchFields?: string[];
orderBy?: any;
@@ -36,6 +45,7 @@ export const getReferenceEntityList = async ({
appliedRelation,
extraSelect,
extraCounts,
+ relationCounts,
extraWhere,
searchFields,
orderBy,
@@ -89,6 +99,12 @@ export const getReferenceEntityList = async ({
applied: true,
},
},
+ ...Object.fromEntries(
+ (relationCounts ?? []).map((rc) => [
+ rc.relation,
+ rc.where ? { where: rc.where } : true,
+ ])
+ ),
},
},
},
@@ -125,15 +141,23 @@ export const getReferenceEntityList = async ({
),
}));
- const dataWithCounts = (data as any[]).map((entity) => ({
- ...entity,
- _count: {
- ...(entity._count ?? {}),
- ...Object.fromEntries(
- maps.map(({ key, counts }) => [key, counts.get(entity.id) ?? 0])
- ),
- },
- }));
+ const dataWithCounts = (data as any[]).map((entity) => {
+ const counts = { ...(entity._count ?? {}) };
+ for (const rc of relationCounts ?? []) {
+ if (rc.key === rc.relation) continue;
+ counts[rc.key] = counts[rc.relation] ?? 0;
+ delete counts[rc.relation];
+ }
+ return {
+ ...entity,
+ _count: {
+ ...counts,
+ ...Object.fromEntries(
+ maps.map(({ key, counts: m }) => [key, m.get(entity.id) ?? 0])
+ ),
+ },
+ };
+ });
return { data: dataWithCounts, total };
};
diff --git a/src/components/admin/CompaniesTable.tsx b/src/components/admin/CompaniesTable.tsx
index 4987c1a..98c5fb8 100644
--- a/src/components/admin/CompaniesTable.tsx
+++ b/src/components/admin/CompaniesTable.tsx
@@ -151,6 +151,7 @@ function CompaniesTable({
<TableHead>Total Jobs</TableHead>
<TableHead>Jobs Applied</TableHead>
<TableHead>Rejected</TableHead>
+ <TableHead>Contacts</TableHead>
</>
)}
<TableHead>Actions</TableHead>
@@ -239,6 +240,9 @@ function CompaniesTable({
<TableCell className="font-medium">
{company._count?.jobsRejected ?? 0}
</TableCell>
+ <TableCell className="font-medium">
+ {company._count?.contacts ?? 0}
+ </TableCell>
</>
)}
<TableCell>
diff --git a/src/lib/wiki/schema.ts b/src/lib/wiki/schema.ts
index 7b2a659..f40d9c2 100644
--- a/src/lib/wiki/schema.ts
+++ b/src/lib/wiki/schema.ts
@@ -13,6 +13,7 @@ export const WIKI_TYPES = [
export const WIKI_FEATURES = [
"setup",
"jobs",
+ "contacts",
"automations",
"profile",
"ai",
diff --git a/src/models/job.model.ts b/src/models/job.model.ts
index 70c2c16..4f06f28 100644
--- a/src/models/job.model.ts
+++ b/src/models/job.model.ts
@@ -94,6 +94,7 @@ export interface Company {
jobsApplied: number;
jobsRejected?: number;
jobsTotal?: number;
+ contacts?: number;
};
}
diff --git a/wiki/contacts.md b/wiki/contacts.md
new file mode 100644
index 0000000..cc91ea4
--- /dev/null
+++ b/wiki/contacts.md
@@ -0,0 +1,62 @@
+---
+type: how-to
+title: Contacts
+description: Keeping the people in your job hunt — recruiters, interviewers and references — linking them to the jobs they touched, and recording how you know them.
+feature: contacts
+tags: [contacts, people, recruiter, hiring manager, interviewer, referrer, reference, roles, contact roles, link a contact, job contacts, relationship, worked together, last contacted, network]
+aliases: [my contacts, people, contact list, recruiters, references, networking]
+status: stable
+stale_after: 2027-08-31
+---
+
+# Contacts
+
+## What are contacts for?
+
+A contact is one person in your job hunt — the recruiter who called, the hiring manager who interviewed you, the former colleague you asked for a referral, the person you list as a reference. Each contact holds their name, title, email, phone, LinkedIn URL, the company they work at now, their location, how you know them, when you last spoke and free-form notes.
+
+Contacts live under **Library → Contacts**, and a contact can be linked to any number of jobs with a role on each link, so the same recruiter can be the recruiter on three different applications.
+
+## How do I add a contact?
+
+Open **Library** in the sidebar, go to the **Contacts** tab and click **New Contact**. Only **Name** is required — everything else can be filled in later by editing the contact, and a name-and-email row is a perfectly useful record on day one.
+
+Company, Location, Role and *Worked together at* are combo boxes: they pick an existing entry or create a new one from what you type, so you never have to set up a company before adding the person who works there. Company is where the person works now; Role is the role they usually play for you, and it is what the role filter matches when the person is not yet on any job.
+
+Click a contact's row to expand it — the expanded row shows their email, phone, LinkedIn, location, how you know them and the jobs they are linked to, without leaving the list.
+
+## How do I link a contact to a job?
+
+Open the job, go to its **Contacts** tab and click **Add Contact**. Pick the person and the role they played on *this* job, and save — the role is per link, so the same person can be the referrer on one job and the interviewer on another.
+
+If the person is not in your contacts yet, the same tab's **New Contact** opens the full contact dialog with whatever you typed already in the Name field, so you can create the person and link them in one pass.
+
+The trash icon beside a linked contact unlinks them from that job only. The contact itself, and every other job they are linked to, is left alone.
+
+## What is a role, and how do I add my own?
+
+A role is the part a person plays: **Recruiter**, **Hiring Manager**, **Interviewer**, **Referrer** and **Reference** are created for you when you sign up. Roles are yours — you can add, rename and delete your own under **Library → Roles**.
+
+Anywhere a Role combo box appears, typing a name that does not exist yet offers to create it, so you do not have to visit the Roles tab first. A role you are using cannot be deleted: the Roles tab refuses with a count of the contacts linked to jobs under it, or of the contacts holding it as their own role. Clear those first, then delete.
+
+## How do I record how I know someone?
+
+The **How you know them** fields on the contact form: **Relationship** in your own words (`my manager`, `peer on the platform team`), **Worked together at** for the company where your paths crossed, and **From** / **To** for the stint. Leave **To** empty for a stint that has not ended — the expanded row then reads `Mar 2021 – present`.
+
+*Worked together at* is deliberately separate from **Company**: Company is where they are now, and the company you overlapped at is often somewhere neither of you still works. **Last contacted** is a plain date you set yourself; nothing updates it for you.
+
+## How do I find my references?
+
+Use the role filter beside the search box on **Library → Contacts** and pick **Reference**. The filter matches both the role on the person and any role they hold on a job, so a reference you have never listed against a job still answers it — as long as their own Role field is set.
+
+A contact with no Role and no job links answers no role filter at all, and shows `—` in the Role column. Set their Role if you want them to be findable that way. The search box next to the filter matches name, email and title, and the two work together.
+
+## Why can't I delete a company or location?
+
+Because a contact points at it. Deleting the company someone works at, or the company you worked together at, would quietly blank that field on the contact rather than fail, so the Library refuses instead and tells you how many contacts are involved. The same applies to a location a contact is in.
+
+Reassign or delete those contacts first, then delete the company or location. Jobs and resume entries block these deletes the same way.
+
+## What happens when I delete a contact?
+
+The person and their job links go; the jobs do not. Deleting a contact removes them from every job's Contacts tab, and nothing else about those jobs changes. There is no undo, so if you only want them off one application, unlink them from that job instead.
diff --git a/wiki/index.md b/wiki/index.md
index 7cc110b..52d9bb2 100644
--- a/wiki/index.md
+++ b/wiki/index.md
@@ -8,6 +8,7 @@ JobSync tracks job applications, resumes and the work you do around them. These
- [Getting Started](./getting-started.md) — create an account, connect an AI provider, add your first job, and what each area of the app is for.
- [Jobs](./jobs.md) — add jobs manually or by pasting a posting into AI chat, move them through the status workflow, edit, filter, export and delete them.
+- [Contacts](./contacts.md) — track recruiters, interviewers and references, link them to the jobs they touched, and record how you know them.
- [Automations](./automations.md) — set up a scheduled search over Greenhouse, Lever and Ashby company boards, fill in the filters that make it work, and handle the jobs it discovers.
- [MCP Access](./mcp.md) — connect an external AI agent such as Claude Desktop, generate and revoke access tokens, and what the agent can do once connected.
diff --git a/wiki/jobs.md b/wiki/jobs.md
index 0b9f796..5e9cc68 100644
--- a/wiki/jobs.md
+++ b/wiki/jobs.md
@@ -37,9 +37,9 @@ The Add Job dialog also has a Status field, so a status can be set when you firs
## What is on a job's details page?
-Three parts, top to bottom. A **header row** with the job title, a `Company · Location · Job Type · Workplace` line, and the actions: Match with AI, Cover Letter, Edit, Delete and a **⋮** menu. Below it a **summary card** of eight facts — Status, Job Type, Salary Range, Source, Applied, AI Match, Resume and Added — with the job URL and any skill badges on a divider row underneath. Below that, four **tabs**.
+Three parts, top to bottom. A **header row** with the job title, a `Company · Location · Job Type · Workplace` line, and the actions: Match with AI, Cover Letter, Edit, Delete and a **⋮** menu. Below it a **summary card** of eight facts — Status, Job Type, Salary Range, Source, Applied, AI Match, Resume and Added — with the job URL and any skill badges on a divider row underneath. Below that, five **tabs**.
-The tabs are **Description**, **AI Match**, **Cover Letter** and **Notes**, and all four are always there. AI Match and Cover Letter stay in the bar even when the job has neither, showing a short explanation and a button to run it — so the tab set never shifts between jobs. Notes carries a count badge once the job has notes. The tab you are on is kept in the address bar, so a refresh, a bookmark or the browser Back button lands you back on the same one.
+The tabs are **Description**, **AI Match**, **Cover Letter**, **Notes** and **[Contacts](./contacts.md)**, and all five are always there. AI Match and Cover Letter stay in the bar even when the job has neither, showing a short explanation and a button to run it — so the tab set never shifts between jobs. Notes and Contacts each carry a count badge once the job has any. Contacts lists the people linked to this job with the role each played. The tab you are on is kept in the address bar, so a refresh, a bookmark or the browser Back button lands you back on the same one.
## How do I edit, annotate or delete a job?