@hasna/contacts 0.6.33 → 0.6.35

package/dist/index.js

@@ -144,7 +144,10 @@ function uuid() {
   return crypto.randomUUID();
 }
 function now() {
-  return new Date().toISOString();
+  const currentMs = Date.now();
+  const nextMs = currentMs > lastNowMs ? currentMs : lastNowMs + 1;
+  lastNowMs = nextMs;
+  return new Date(nextMs).toISOString();
 }
 function quoteIdentifier(identifier) {
   return `"${identifier.replaceAll('"', '""')}"`;
@@ -182,7 +185,7 @@ function runMigrations(db) {
     db.exec(`INSERT OR REPLACE INTO _migrations(version) VALUES(${i})`);
   }
 }
-var MIGRATIONS, _db = null;
+var MIGRATIONS, _db = null, lastNowMs = 0;
 var init_database = __esm(() => {
   init_sqlite_adapter();
   init_paths();
@@ -754,6 +757,81 @@ var init_database = __esm(() => {
   );
 
   CREATE INDEX IF NOT EXISTS idx_contacts_tombstones_deleted_at ON _contacts_tombstones(deleted_at);
+  `,
+    `
+  CREATE TABLE IF NOT EXISTS contact_project_membership_states (
+    contact_id TEXT NOT NULL REFERENCES contacts(id) ON DELETE CASCADE,
+    project_id TEXT NOT NULL,
+    linked INTEGER NOT NULL CHECK(linked IN (0, 1)),
+    revision INTEGER NOT NULL DEFAULT 0 CHECK(revision >= 0),
+    updated_at TEXT NOT NULL,
+    PRIMARY KEY (contact_id, project_id)
+  );
+
+  INSERT OR IGNORE INTO contact_project_membership_states
+    (contact_id, project_id, linked, revision, updated_at)
+  SELECT contact_id, project_id, 1, 0, datetime('now')
+  FROM contact_projects;
+
+  CREATE TABLE IF NOT EXISTS contact_project_membership_receipts (
+    receipt_id TEXT PRIMARY KEY,
+    direction TEXT NOT NULL CHECK(direction IN ('attach', 'detach')),
+    contact_id TEXT NOT NULL REFERENCES contacts(id) ON DELETE CASCADE,
+    project_id TEXT NOT NULL,
+    operation_id TEXT NOT NULL,
+    step_id TEXT NOT NULL,
+    expected_version TEXT NOT NULL,
+    before_json TEXT NOT NULL,
+    after_json TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    UNIQUE(operation_id, step_id)
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_contact_project_membership_states_project
+    ON contact_project_membership_states(project_id, linked, contact_id);
+  CREATE INDEX IF NOT EXISTS idx_contact_project_membership_receipts_target
+    ON contact_project_membership_receipts(contact_id, project_id, created_at);
+
+  CREATE TRIGGER IF NOT EXISTS sync_contact_project_membership_state_after_insert
+  AFTER INSERT ON contact_projects
+  BEGIN
+    INSERT INTO contact_project_membership_states
+      (contact_id, project_id, linked, revision, updated_at)
+    VALUES (NEW.contact_id, NEW.project_id, 1, 1, datetime('now'))
+    ON CONFLICT(contact_id, project_id) DO UPDATE SET
+      linked = 1,
+      revision = CASE
+        WHEN contact_project_membership_states.linked = 1
+          THEN contact_project_membership_states.revision
+        ELSE contact_project_membership_states.revision + 1
+      END,
+      updated_at = CASE
+        WHEN contact_project_membership_states.linked = 1
+          THEN contact_project_membership_states.updated_at
+        ELSE datetime('now')
+      END;
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS sync_contact_project_membership_state_after_delete
+  AFTER DELETE ON contact_projects
+  WHEN EXISTS (SELECT 1 FROM contacts WHERE id = OLD.contact_id)
+  BEGIN
+    INSERT INTO contact_project_membership_states
+      (contact_id, project_id, linked, revision, updated_at)
+    VALUES (OLD.contact_id, OLD.project_id, 0, 1, datetime('now'))
+    ON CONFLICT(contact_id, project_id) DO UPDATE SET
+      linked = 0,
+      revision = CASE
+        WHEN contact_project_membership_states.linked = 0
+          THEN contact_project_membership_states.revision
+        ELSE contact_project_membership_states.revision + 1
+      END,
+      updated_at = CASE
+        WHEN contact_project_membership_states.linked = 0
+          THEN contact_project_membership_states.updated_at
+        ELSE datetime('now')
+      END;
+  END;
   `
   ];
 });
@@ -853,6 +931,219 @@ var init_tombstones = __esm(() => {
   init_database();
 });
 
+// src/types/project-memberships.ts
+var ContactProjectMembershipConflictError;
+var init_project_memberships = __esm(() => {
+  ContactProjectMembershipConflictError = class ContactProjectMembershipConflictError extends Error {
+    constructor(message) {
+      super(message);
+      this.name = "ContactProjectMembershipConflictError";
+    }
+  };
+});
+
+// src/db/project-memberships.ts
+import { createHash } from "crypto";
+function digest(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+function membershipVersion(contactId, projectId, linked, revision) {
+  return `cpmv_${digest(JSON.stringify([contactId, projectId, linked, revision])).slice(0, 32)}`;
+}
+function receiptId(input) {
+  return `cpmr_${digest(JSON.stringify([
+    input.operation_id,
+    input.step_id,
+    input.contact_id,
+    input.project_id
+  ])).slice(0, 32)}`;
+}
+function stateRow(contactId, projectId, db) {
+  const persisted = db.query(`SELECT contact_id, project_id, linked, revision
+     FROM contact_project_membership_states
+     WHERE contact_id = ? AND project_id = ?`).get(contactId, projectId);
+  if (persisted)
+    return persisted;
+  const linked = Boolean(db.query(`SELECT 1 AS present FROM contact_projects WHERE contact_id = ? AND project_id = ?`).get(contactId, projectId));
+  return { contact_id: contactId, project_id: projectId, linked: linked ? 1 : 0, revision: 0 };
+}
+function snapshot(row) {
+  const linked = Boolean(row.linked);
+  return {
+    contact_id: row.contact_id,
+    project_id: row.project_id,
+    linked,
+    version: membershipVersion(row.contact_id, row.project_id, linked, row.revision)
+  };
+}
+function required(value, name) {
+  const normalized = value.trim();
+  if (!normalized)
+    throw new Error(`${name} is required`);
+  return normalized;
+}
+function normalizeInput(input) {
+  return {
+    contact_id: required(input.contact_id, "contact_id"),
+    project_id: required(input.project_id, "project_id"),
+    operation_id: required(input.operation_id, "operation_id"),
+    step_id: required(input.step_id, "step_id"),
+    expected_version: required(input.expected_version, "expected_version")
+  };
+}
+function parseSnapshot(value) {
+  return JSON.parse(value);
+}
+function replay(row, direction, input) {
+  if (row.direction !== direction || row.contact_id !== input.contact_id || row.project_id !== input.project_id || row.expected_version !== input.expected_version) {
+    throw new ContactProjectMembershipConflictError(`operation_id/step_id already accepted for a different contact-project membership mutation`);
+  }
+  return {
+    outcome: "duplicate_of_accepted",
+    operation_id: row.operation_id,
+    step_id: row.step_id,
+    before: parseSnapshot(row.before_json),
+    after: parseSnapshot(row.after_json),
+    receipt_id: row.receipt_id
+  };
+}
+function transitionWithoutReceipt(contactId, projectId, linked, db) {
+  const beforeRow = stateRow(contactId, projectId, db);
+  const changed = Boolean(beforeRow.linked) !== linked;
+  const afterRow = {
+    ...beforeRow,
+    linked: linked ? 1 : 0,
+    revision: changed ? beforeRow.revision + 1 : beforeRow.revision
+  };
+  const changedAt = now();
+  db.run(`INSERT INTO contact_project_membership_states
+       (contact_id, project_id, linked, revision, updated_at)
+     VALUES (?, ?, ?, ?, ?)
+     ON CONFLICT(contact_id, project_id) DO UPDATE SET
+       linked = excluded.linked,
+       revision = excluded.revision,
+       updated_at = excluded.updated_at`, [contactId, projectId, afterRow.linked, afterRow.revision, changedAt]);
+  if (linked) {
+    db.run(`INSERT OR IGNORE INTO contact_projects (contact_id, project_id) VALUES (?, ?)`, [contactId, projectId]);
+  } else {
+    db.run(`DELETE FROM contact_projects WHERE contact_id = ? AND project_id = ?`, [contactId, projectId]);
+  }
+  return changed;
+}
+function setContactProjectMembershipWithoutReceipt(contactId, projectId, linked, db = getDatabase()) {
+  const normalizedContactId = required(contactId, "contact_id");
+  const normalizedProjectId = required(projectId, "project_id");
+  return db.transaction(() => transitionWithoutReceipt(normalizedContactId, normalizedProjectId, linked, db));
+}
+function replaceContactProjectMembershipsWithoutReceipts(contactId, projectIds, db = getDatabase()) {
+  const normalizedContactId = required(contactId, "contact_id");
+  const normalizedProjectIds = [...new Set(projectIds.map((projectId) => required(projectId, "project_id")))];
+  return db.transaction(() => {
+    const currentRows = db.query(`SELECT project_id FROM contact_projects WHERE contact_id = ?`).all(normalizedContactId);
+    const desired = new Set(normalizedProjectIds);
+    const population = new Set([...currentRows.map((row) => row.project_id), ...normalizedProjectIds]);
+    for (const projectId of population) {
+      transitionWithoutReceipt(normalizedContactId, projectId, desired.has(projectId), db);
+    }
+    return normalizedProjectIds;
+  });
+}
+function readContactProjectMembership(contactId, projectId, db = getDatabase()) {
+  return snapshot(stateRow(required(contactId, "contact_id"), required(projectId, "project_id"), db));
+}
+function listContactProjectMemberships(projectId, maxItems, db = getDatabase()) {
+  const normalizedProjectId = required(projectId, "project_id");
+  if (!Number.isInteger(maxItems) || maxItems < 1)
+    throw new Error("max_items must be a positive integer");
+  const rows = db.query(`SELECT cp.contact_id, cp.project_id,
+            COALESCE(state.linked, 1) AS linked,
+            COALESCE(state.revision, 0) AS revision
+     FROM contact_projects cp
+     LEFT JOIN contact_project_membership_states state
+       ON state.contact_id = cp.contact_id AND state.project_id = cp.project_id
+     WHERE cp.project_id = ?
+     ORDER BY cp.contact_id ASC
+     LIMIT ?`).all(normalizedProjectId, maxItems + 1);
+  if (rows.length > maxItems) {
+    throw new Error(`contact project membership collection exceeds max_items=${maxItems}`);
+  }
+  const contactIds = rows.map((row) => row.contact_id);
+  return {
+    project_id: normalizedProjectId,
+    contact_ids: contactIds,
+    complete: true,
+    membership_revision: `cpml_${digest(JSON.stringify(rows.map((row) => snapshot(row)))).slice(0, 32)}`
+  };
+}
+function mutateContactProjectMembership(direction, rawInput, db = getDatabase()) {
+  const input = normalizeInput(rawInput);
+  return db.transaction(() => {
+    const existingReceipt = db.query(`SELECT direction, contact_id, project_id, operation_id, step_id, expected_version,
+              before_json, after_json, receipt_id
+       FROM contact_project_membership_receipts
+       WHERE operation_id = ? AND step_id = ?`).get(input.operation_id, input.step_id);
+    if (existingReceipt)
+      return replay(existingReceipt, direction, input);
+    const contact = db.query(`SELECT id FROM contacts WHERE id = ?`).get(input.contact_id);
+    if (!contact)
+      throw new Error(`contact not found: ${input.contact_id}`);
+    const beforeRow = stateRow(input.contact_id, input.project_id, db);
+    const before = snapshot(beforeRow);
+    if (before.version !== input.expected_version) {
+      throw new ContactProjectMembershipConflictError(`contact project membership expected_version conflict: expected ${input.expected_version}, current ${before.version}`);
+    }
+    const desiredLinked = direction === "attach";
+    const changed = before.linked !== desiredLinked;
+    const afterRow = {
+      ...beforeRow,
+      linked: desiredLinked ? 1 : 0,
+      revision: changed ? beforeRow.revision + 1 : beforeRow.revision
+    };
+    const changedAt = now();
+    db.run(`INSERT INTO contact_project_membership_states
+        (contact_id, project_id, linked, revision, updated_at)
+       VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(contact_id, project_id) DO UPDATE SET
+         linked = excluded.linked,
+         revision = excluded.revision,
+         updated_at = excluded.updated_at`, [input.contact_id, input.project_id, afterRow.linked, afterRow.revision, changedAt]);
+    if (desiredLinked) {
+      db.run(`INSERT OR IGNORE INTO contact_projects (contact_id, project_id) VALUES (?, ?)`, [input.contact_id, input.project_id]);
+    } else {
+      db.run(`DELETE FROM contact_projects WHERE contact_id = ? AND project_id = ?`, [input.contact_id, input.project_id]);
+    }
+    const after = snapshot(afterRow);
+    const id = receiptId(input);
+    db.run(`INSERT INTO contact_project_membership_receipts (
+         receipt_id, direction, contact_id, project_id, operation_id, step_id,
+         expected_version, before_json, after_json, created_at
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+      id,
+      direction,
+      input.contact_id,
+      input.project_id,
+      input.operation_id,
+      input.step_id,
+      input.expected_version,
+      JSON.stringify(before),
+      JSON.stringify(after),
+      changedAt
+    ]);
+    return {
+      outcome: changed ? "accepted" : "duplicate_of_accepted",
+      operation_id: input.operation_id,
+      step_id: input.step_id,
+      before,
+      after,
+      receipt_id: id
+    };
+  });
+}
+var init_project_memberships2 = __esm(() => {
+  init_database();
+  init_project_memberships();
+});
+
 // src/db/contacts.ts
 var exports_contacts = {};
 __export(exports_contacts, {
@@ -1451,34 +1742,32 @@ function autoLinkContactToCompany(contactId, db) {
 }
 function linkContactToProject(contactId, projectId, db) {
   const d = db || getDatabase();
-  d.run(`INSERT OR IGNORE INTO contact_projects (contact_id, project_id) VALUES (?, ?)`, [contactId, projectId]);
+  setContactProjectMembershipWithoutReceipt(contactId, projectId, true, d);
 }
 function unlinkContactFromProject(contactId, projectId, db) {
   const d = db || getDatabase();
-  d.run(`DELETE FROM contact_projects WHERE contact_id = ? AND project_id = ?`, [contactId, projectId]);
+  setContactProjectMembershipWithoutReceipt(contactId, projectId, false, d);
 }
 function getContactProjectIds(contactId, db) {
   const d = db || getDatabase();
-  const rows = d.query(`SELECT project_id FROM contact_projects WHERE contact_id = ?`).all(contactId);
+  const rows = d.query(`SELECT project_id FROM contact_projects WHERE contact_id = ? ORDER BY project_id ASC`).all(contactId);
   return rows.map((r) => r.project_id);
 }
 function listContactIdsByProject(projectId, db) {
   const d = db || getDatabase();
-  const rows = d.query(`SELECT contact_id FROM contact_projects WHERE project_id = ?`).all(projectId);
+  const rows = d.query(`SELECT contact_id FROM contact_projects WHERE project_id = ? ORDER BY contact_id ASC`).all(projectId);
   return rows.map((r) => r.contact_id);
 }
 function setContactProjects(contactId, projectIds, db) {
   const d = db || getDatabase();
-  d.run(`DELETE FROM contact_projects WHERE contact_id = ?`, [contactId]);
-  for (const pid of projectIds) {
-    d.run(`INSERT OR IGNORE INTO contact_projects (contact_id, project_id) VALUES (?, ?)`, [contactId, pid]);
-  }
+  replaceContactProjectMembershipsWithoutReceipts(contactId, projectIds, d);
 }
 var init_contacts = __esm(() => {
   init_types();
   init_database();
   init_activity();
   init_tombstones();
+  init_project_memberships2();
 });
 
 // src/db/events.ts
@@ -1644,6 +1933,7 @@ function getStorageStatus(db = getDatabase()) {
 
 // src/store/index.ts
 init_contacts();
+init_project_memberships2();
 
 // src/db/companies.ts
 init_types();
@@ -3173,7 +3463,7 @@ init_database();
 init_database();
 import { existsSync as existsSync3, readFileSync, writeFileSync, mkdirSync as mkdirSync3, unlinkSync } from "fs";
 import { join as join2 } from "path";
-import { createCipheriv, createDecipheriv, randomBytes, pbkdf2Sync, createHash } from "crypto";
+import { createCipheriv, createDecipheriv, randomBytes, pbkdf2Sync, createHash as createHash2 } from "crypto";
 var VAULT_DIR = getDataDir();
 var VAULT_CONFIG = join2(VAULT_DIR, "vault.json");
 var VAULT_SESSION = join2(VAULT_DIR, ".vault-session");
@@ -3219,7 +3509,7 @@ function initVault(passphrase) {
     mkdirSync3(DOCUMENTS_DIR, { recursive: true });
   const salt = randomBytes(32);
   const key = deriveKey(passphrase, salt);
-  const keyHash = createHash("sha256").update(key).digest("hex");
+  const keyHash = createHash2("sha256").update(key).digest("hex");
   const config = { salt: salt.toString("hex"), key_hash: keyHash, created_at: new Date().toISOString() };
   writeFileSync(VAULT_CONFIG, JSON.stringify(config, null, 2));
   _derivedKey = key;
@@ -3234,7 +3524,7 @@ function unlockVault(passphrase) {
   const config = JSON.parse(readFileSync(VAULT_CONFIG, "utf-8"));
   const salt = Buffer.from(config.salt, "hex");
   const key = deriveKey(passphrase, salt);
-  const keyHash = createHash("sha256").update(key).digest("hex");
+  const keyHash = createHash2("sha256").update(key).digest("hex");
   if (keyHash !== config.key_hash)
     return false;
   _derivedKey = key;
@@ -4749,6 +5039,15 @@ class LocalStore {
   async listContactIdsByProject(projectId) {
     return listContactIdsByProject(projectId, this.db);
   }
+  async readContactProjectMembership(contactId, projectId) {
+    return readContactProjectMembership(contactId, projectId, this.db);
+  }
+  async listContactProjectMemberships(projectId, maxItems) {
+    return listContactProjectMemberships(projectId, maxItems, this.db);
+  }
+  async mutateContactProjectMembership(direction, input) {
+    return mutateContactProjectMembership(direction, input, this.db);
+  }
   async createCompany(input) {
     return createCompany(input, this.db);
   }
@@ -5371,20 +5670,33 @@ class ApiStore {
   async findContactByEmailAddress(address) {
     return this.getContactByEmail(address);
   }
-  async linkContactToProject() {
-    return unavailable("linkContactToProject");
+  async linkContactToProject(contactId, projectId) {
+    await this.client.transport.put(`/contacts/${this.enc(contactId)}/projects/${this.enc(projectId)}`);
+  }
+  async unlinkContactFromProject(contactId, projectId) {
+    await this.del(`/contacts/${this.enc(contactId)}/projects/${this.enc(projectId)}`);
+  }
+  async getContactProjectIds(contactId) {
+    return pick(await this.g(`/contacts/${this.enc(contactId)}/projects`), "project_ids") ?? [];
   }
-  async unlinkContactFromProject() {
-    return unavailable("unlinkContactFromProject");
+  async setContactProjects(contactId, projectIds) {
+    await this.client.transport.put(`/contacts/${this.enc(contactId)}/projects`, { project_ids: projectIds });
   }
-  async getContactProjectIds() {
-    return unavailable("getContactProjectIds");
+  async listContactIdsByProject(projectId) {
+    return pick(await this.g(`/projects/${this.enc(projectId)}/contacts`), "contact_ids") ?? [];
   }
-  async setContactProjects() {
-    return unavailable("setContactProjects");
+  async readContactProjectMembership(contactId, projectId) {
+    return this.client.transport.get(`/projects/${this.enc(projectId)}/contact-memberships/${this.enc(contactId)}`);
   }
-  async listContactIdsByProject() {
-    return unavailable("listContactIdsByProject");
+  async listContactProjectMemberships(projectId, maxItems) {
+    return this.client.transport.get(`/projects/${this.enc(projectId)}/contact-memberships`, { query: { max_items: maxItems } });
+  }
+  async mutateContactProjectMembership(direction, input) {
+    return this.client.transport.post(`/projects/${this.enc(input.project_id)}/contact-memberships/${this.enc(input.contact_id)}/${direction}`, {
+      operation_id: input.operation_id,
+      step_id: input.step_id,
+      expected_version: input.expected_version
+    });
   }
   async createCompany(input) {
     const res = await this.client.create("companies", stripUndefined(input));
@@ -5907,6 +6219,7 @@ function resetStoreCache() {
 }
 
 // src/index.ts
+init_project_memberships();
 init_types();
 
 // src/sdk/v1.generated.ts
@@ -6013,6 +6326,34 @@ class ContactsV1Client {
       init
     });
   }
+  async getContactProjectIds(contactId, init) {
+    return this.request("GET", `/v1/contacts/${encodeURIComponent(String(contactId))}/projects`, {
+      body: undefined,
+      query: undefined,
+      init
+    });
+  }
+  async setContactProjects(contactId, body, init) {
+    return this.request("PUT", `/v1/contacts/${encodeURIComponent(String(contactId))}/projects`, {
+      body,
+      query: undefined,
+      init
+    });
+  }
+  async linkContactToProject(contactId, projectId, init) {
+    return this.request("PUT", `/v1/contacts/${encodeURIComponent(String(contactId))}/projects/${encodeURIComponent(String(projectId))}`, {
+      body: undefined,
+      query: undefined,
+      init
+    });
+  }
+  async unlinkContactFromProject(contactId, projectId, init) {
+    return this.request("DELETE", `/v1/contacts/${encodeURIComponent(String(contactId))}/projects/${encodeURIComponent(String(projectId))}`, {
+      body: undefined,
+      query: undefined,
+      init
+    });
+  }
   async addTagToContact(contactId, tagId, init) {
     return this.request("PUT", `/v1/contacts/${encodeURIComponent(String(contactId))}/tags/${encodeURIComponent(String(tagId))}`, {
       body: undefined,
@@ -6048,6 +6389,41 @@ class ContactsV1Client {
       init
     });
   }
+  async listContactProjectMemberships(projectId, query, init) {
+    return this.request("GET", `/v1/projects/${encodeURIComponent(String(projectId))}/contact-memberships`, {
+      body: undefined,
+      query,
+      init
+    });
+  }
+  async readContactProjectMembership(projectId, contactId, init) {
+    return this.request("GET", `/v1/projects/${encodeURIComponent(String(projectId))}/contact-memberships/${encodeURIComponent(String(contactId))}`, {
+      body: undefined,
+      query: undefined,
+      init
+    });
+  }
+  async attachContactProjectMembership(projectId, contactId, body, init) {
+    return this.request("POST", `/v1/projects/${encodeURIComponent(String(projectId))}/contact-memberships/${encodeURIComponent(String(contactId))}/attach`, {
+      body,
+      query: undefined,
+      init
+    });
+  }
+  async detachContactProjectMembership(projectId, contactId, body, init) {
+    return this.request("POST", `/v1/projects/${encodeURIComponent(String(projectId))}/contact-memberships/${encodeURIComponent(String(contactId))}/detach`, {
+      body,
+      query: undefined,
+      init
+    });
+  }
+  async listContactIdsByProject(projectId, init) {
+    return this.request("GET", `/v1/projects/${encodeURIComponent(String(projectId))}/contacts`, {
+      body: undefined,
+      query: undefined,
+      init
+    });
+  }
   async getStats(init) {
     return this.request("GET", `/v1/stats`, {
       body: undefined,
@@ -6123,6 +6499,7 @@ function getPackageVersion() {
 // src/server/openapi.ts
 var contactSchema = {
   type: "object",
+  required: ["tags"],
   properties: {
     id: { type: "string" },
     first_name: { type: "string" },
@@ -6137,6 +6514,7 @@ var contactSchema = {
     sensitivity: { type: "string" },
     archived: { type: "boolean" },
     priority: { type: "number" },
+    tags: { type: "array", items: { $ref: "#/components/schemas/Tag" } },
     created_at: { type: "string" },
     updated_at: { type: "string" }
   }
@@ -6256,6 +6634,58 @@ function buildV1OpenApiDocument(version = getPackageVersion()) {
             color: { type: "string" },
             description: { type: "string" }
           }
+        },
+        ProjectIdsInput: {
+          type: "object",
+          required: ["project_ids"],
+          properties: {
+            project_ids: {
+              type: "array",
+              items: { type: "string", minLength: 1 },
+              uniqueItems: true
+            }
+          }
+        },
+        ContactProjectMembershipSnapshot: {
+          type: "object",
+          required: ["contact_id", "project_id", "linked", "version"],
+          properties: {
+            contact_id: { type: "string" },
+            project_id: { type: "string" },
+            linked: { type: "boolean" },
+            version: { type: "string" }
+          }
+        },
+        ContactProjectMembershipMutationInput: {
+          type: "object",
+          required: ["operation_id", "step_id", "expected_version"],
+          properties: {
+            operation_id: { type: "string", minLength: 1 },
+            step_id: { type: "string", minLength: 1 },
+            expected_version: { type: "string", minLength: 1 }
+          }
+        },
+        ContactProjectMembershipMutationResult: {
+          type: "object",
+          required: ["outcome", "operation_id", "step_id", "before", "after", "receipt_id"],
+          properties: {
+            outcome: { type: "string", enum: ["accepted", "duplicate_of_accepted"] },
+            operation_id: { type: "string" },
+            step_id: { type: "string" },
+            before: { $ref: "#/components/schemas/ContactProjectMembershipSnapshot" },
+            after: { $ref: "#/components/schemas/ContactProjectMembershipSnapshot" },
+            receipt_id: { type: "string" }
+          }
+        },
+        ContactProjectMembershipListResult: {
+          type: "object",
+          required: ["project_id", "contact_ids", "complete", "membership_revision"],
+          properties: {
+            project_id: { type: "string" },
+            contact_ids: { type: "array", items: { type: "string" } },
+            complete: { type: "boolean", const: true },
+            membership_revision: { type: "string" }
+          }
         }
       }
     },
@@ -6269,6 +6699,7 @@ function buildV1OpenApiDocument(version = getPackageVersion()) {
             { name: "q", in: "query", schema: { type: "string" } },
             { name: "company_id", in: "query", schema: { type: "string" } },
             { name: "status", in: "query", schema: { type: "string" } },
+            { name: "tag_id", in: "query", schema: { type: "string" } },
             { name: "limit", in: "query", schema: { type: "number" } },
             { name: "offset", in: "query", schema: { type: "number" } }
           ],
@@ -6455,6 +6886,167 @@ function buildV1OpenApiDocument(version = getPackageVersion()) {
           })
         }
       },
+      "/v1/contacts/{contact_id}/projects": {
+        get: {
+          operationId: "getContactProjectIds",
+          summary: "List project ids attached to a contact",
+          parameters: [
+            { name: "contact_id", in: "path", required: true, schema: { type: "string" } }
+          ],
+          responses: objResponse({
+            contact_id: { type: "string" },
+            project_ids: { type: "array", items: { type: "string" } }
+          })
+        },
+        put: {
+          operationId: "setContactProjects",
+          summary: "Atomically replace a contact's project memberships",
+          parameters: [
+            { name: "contact_id", in: "path", required: true, schema: { type: "string" } }
+          ],
+          requestBody: {
+            required: true,
+            content: { "application/json": { schema: { $ref: "#/components/schemas/ProjectIdsInput" } } }
+          },
+          responses: objResponse({
+            contact_id: { type: "string" },
+            project_ids: { type: "array", items: { type: "string" } }
+          })
+        }
+      },
+      "/v1/contacts/{contact_id}/projects/{project_id}": {
+        put: {
+          operationId: "linkContactToProject",
+          summary: "Attach a contact to a project idempotently",
+          parameters: [
+            { name: "contact_id", in: "path", required: true, schema: { type: "string" } },
+            { name: "project_id", in: "path", required: true, schema: { type: "string" } }
+          ],
+          responses: objResponse({
+            attached: { type: "boolean" },
+            contact_id: { type: "string" },
+            project_id: { type: "string" }
+          })
+        },
+        delete: {
+          operationId: "unlinkContactFromProject",
+          summary: "Detach a contact from a project",
+          parameters: [
+            { name: "contact_id", in: "path", required: true, schema: { type: "string" } },
+            { name: "project_id", in: "path", required: true, schema: { type: "string" } }
+          ],
+          responses: objResponse({
+            removed: { type: "boolean" },
+            contact_id: { type: "string" },
+            project_id: { type: "string" }
+          })
+        }
+      },
+      "/v1/projects/{project_id}/contacts": {
+        get: {
+          operationId: "listContactIdsByProject",
+          summary: "List contact ids attached to a project",
+          parameters: [
+            { name: "project_id", in: "path", required: true, schema: { type: "string" } }
+          ],
+          responses: objResponse({
+            project_id: { type: "string" },
+            contact_ids: { type: "array", items: { type: "string" } }
+          })
+        }
+      },
+      "/v1/projects/{project_id}/contact-memberships": {
+        get: {
+          operationId: "listContactProjectMemberships",
+          summary: "List the complete authoritative contact membership collection for a project",
+          parameters: [
+            { name: "project_id", in: "path", required: true, schema: { type: "string" } },
+            { name: "max_items", in: "query", required: true, schema: { type: "integer", minimum: 1 } }
+          ],
+          responses: {
+            "200": {
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ContactProjectMembershipListResult" }
+                }
+              }
+            }
+          }
+        }
+      },
+      "/v1/projects/{project_id}/contact-memberships/{contact_id}": {
+        get: {
+          operationId: "readContactProjectMembership",
+          summary: "Read one authoritative contact-project membership snapshot",
+          parameters: [
+            { name: "project_id", in: "path", required: true, schema: { type: "string" } },
+            { name: "contact_id", in: "path", required: true, schema: { type: "string" } }
+          ],
+          responses: {
+            "200": {
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ContactProjectMembershipSnapshot" }
+                }
+              }
+            }
+          }
+        }
+      },
+      "/v1/projects/{project_id}/contact-memberships/{contact_id}/attach": {
+        post: {
+          operationId: "attachContactProjectMembership",
+          summary: "Attach a contact to a project under expected-version CAS with a replay-safe receipt",
+          parameters: [
+            { name: "project_id", in: "path", required: true, schema: { type: "string" } },
+            { name: "contact_id", in: "path", required: true, schema: { type: "string" } }
+          ],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/ContactProjectMembershipMutationInput" }
+              }
+            }
+          },
+          responses: {
+            "200": {
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ContactProjectMembershipMutationResult" }
+                }
+              }
+            }
+          }
+        }
+      },
+      "/v1/projects/{project_id}/contact-memberships/{contact_id}/detach": {
+        post: {
+          operationId: "detachContactProjectMembership",
+          summary: "Detach a contact from a project under expected-version CAS with a replay-safe receipt",
+          parameters: [
+            { name: "project_id", in: "path", required: true, schema: { type: "string" } },
+            { name: "contact_id", in: "path", required: true, schema: { type: "string" } }
+          ],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/ContactProjectMembershipMutationInput" }
+              }
+            }
+          },
+          responses: {
+            "200": {
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ContactProjectMembershipMutationResult" }
+                }
+              }
+            }
+          }
+        }
+      },
       "/v1/stats": {
         get: {
           operationId: "getStats",
@@ -6479,6 +7071,7 @@ export {
   DuplicateAudienceIdError,
   ContactsV1Client,
   ApiError as ContactsV1ApiError,
+  ContactProjectMembershipConflictError,
   ContactNotFoundError,
   CompanyNotFoundError,
   CONSENT_STATUSES,