contacts: my book, the company book, vCard/CSV import, sharing with Accept/Deny

C1 (spec 11): /api/me/contacts and /api/contacts (admin), our own vCard 2.1/3.0/4.0 and CSV
readers with a preview, contact_shares (migration 0009) for offers, and contact names in call
history, voicemail, Home, the softphone and the call report email. Admin → Contacts.
This commit is contained in:
iamdoubz committed 2026-10-23 14:53:21 -05:00
1 parent 32f4590369
commit a754974a90
26 files changed
+6103 -23

No files matched your search

+123
View File
@@ -0,0 +1,123 @@
// SPDX-License-Identifier: AGPL-3.0-or-later
// The builtin address books (11 §3): a user's (owner_user_id) and the company's (null).
// ponytail: builtin only. Contrack (C3) adds its provider here, behind the same functions.
import { asc, eq, isNull, or, sql } from 'drizzle-orm';
import {
normalizeNumber,
type ContactData,
type ContactDto,
type ContactImportResult,
} from '@selfphoneng/shared';
import type { Db } from '../db/client.ts';
import { contacts } from '../db/schema.ts';
import { badRequest } from '../errors.ts';
/** null = the company book. */
export type Owner = string | null;
const inBook = (owner: Owner) =>
owner ? eq(contacts.ownerUserId, owner) : isNull(contacts.ownerUserId);
type Row = typeof contacts.$inferSelect;
export const toDto = (r: Row): ContactDto => ({
id: r.id,
book: r.ownerUserId ? 'mine' : 'company',
name: r.name,
company: r.company,
email: r.email,
numbers: r.numbers as ContactData['numbers'],
notes: r.notes,
});
/** Normalized numbers (00 §8); `bad` gets the ones that aren't phone numbers. */
export function cleanNumbers(c: ContactData, bad?: (n: string) => void): ContactData['numbers'] {
const out: ContactData['numbers'] = [];
for (const n of c.numbers)
try {
const number = normalizeNumber(n.number);
if (!out.some((o) => o.number === number)) out.push({ label: n.label, number });
} catch {
if (!bad) throw badRequest(`"${n.number}" isn't a phone number`);
bad(n.number);
}
return out;
}
/** My contacts, then the company's, by name. */
export async function listBooks(db: Db, userId: string): Promise<ContactDto[]> {
const rows = await db
.select()
.from(contacts)
.where(or(eq(contacts.ownerUserId, userId), isNull(contacts.ownerUserId)))
.orderBy(sql`${contacts.ownerUserId} is null`, asc(contacts.name));
return rows.map(toDto);
}
export async function listBook(db: Db, owner: Owner): Promise<ContactDto[]> {
return (await db.select().from(contacts).where(inBook(owner)).orderBy(asc(contacts.name))).map(
toDto,
);
}
/** Same contact: same name (any case) and a number in common, or neither has a number. */
const sameKey = (c: ContactData) => c.name.trim().toLowerCase();
const isDuplicate = (a: ContactData, b: ContactData) =>
sameKey(a) === sameKey(b) &&
((!a.numbers.length && !b.numbers.length) ||
a.numbers.some((n) => b.numbers.some((m) => m.number === n.number)));
/**
* Adds contacts to a book, skipping ones it already has (11 §3.1). With `commit` false it only
* counts. Bad numbers are dropped and reported.
*/
export async function addToBook(
db: Pick<Db, 'select' | 'insert'>, // a transaction too
owner: Owner,
list: ContactData[],
commit: boolean,
errors: string[] = [],
): Promise<ContactImportResult> {
const have = (await db.select().from(contacts).where(inBook(owner))).map(toDto);
const fresh: ContactData[] = [];
let duplicates = 0;
for (const c of list) {
const numbers = cleanNumbers(c, (n) =>
errors.push(`${c.name}: "${n}" isn't a phone number, left out`),
);
const clean = { ...c, numbers };
if ([...have, ...fresh].some((h) => isDuplicate(h, clean))) duplicates++;
else fresh.push(clean);
}
// ponytail: one insert of up to 5,000 rows (the import cap).
if (commit && fresh.length)
await db.insert(contacts).values(fresh.map((c) => ({ ...c, ownerUserId: owner })));
return {
committed: commit,
added: fresh.length,
duplicates,
noNumber: fresh.filter((c) => !c.numbers.length).length,
errors: errors.slice(0, 20),
};
}
/**
* Names for numbers, from my book first, then the company's (11 §1). Numbers as calls store them
* (normalized).
*/
export async function contactNames(
db: Db,
userId: string | null,
numbers: (string | null)[],
): Promise<Map<string, string>> {
const want = [...new Set(numbers.filter((n): n is string => !!n))];
const out = new Map<string, string>();
if (!want.length) return out;
// ponytail: a scan of the two books' numbers; a GIN index when books reach tens of thousands.
const { rows } = await db.execute<{ name: string; number: string; mine: boolean }>(sql`
select c.name, n->>'number' as number, c.owner_user_id is not null as mine
from ${contacts} c, jsonb_array_elements(c.numbers) n
where ${userId ? sql`(c.owner_user_id = ${userId} or c.owner_user_id is null)` : sql`c.owner_user_id is null`}
and n->>'number' in ${want}`);
for (const r of rows.sort((a, b) => Number(b.mine) - Number(a.mine)))
if (!out.has(r.number)) out.set(r.number, r.name);
return out;
}
+68
View File
@@ -0,0 +1,68 @@
// SPDX-License-Identifier: AGPL-3.0-or-later
// CSV to contacts (04 §7.4): name,company,email,label1,number1,label2,number2,… with a header row
// (any order, any case; notes too).
import type { ContactData } from '@selfphoneng/shared';
/** RFC 4180 rows (blank ones too): quoted cells may hold commas, quotes ("") and line breaks. */
export function csvRows(input: string): string[][] {
const rows: string[][] = [];
let row: string[] = [];
let cell = '';
let quoted = false;
const s = input.replace(/^\uFEFF/, '');
for (let i = 0; i < s.length; i++) {
const c = s[i]!;
if (quoted) {
if (c === '"' && s[i + 1] === '"') {
cell += '"';
i++;
} else if (c === '"') quoted = false;
else cell += c;
} else if (c === '"') quoted = true;
else if (c === ',') {
row.push(cell);
cell = '';
} else if (c === '\n' || c === '\r') {
if (c === '\r' && s[i + 1] === '\n') i++;
row.push(cell);
rows.push(row);
row = [];
cell = '';
} else cell += c;
}
if (cell || row.length) rows.push([...row, cell]);
return rows;
}
export function parseCsv(input: string): { contacts: ContactData[]; errors: string[] } {
const [header, ...rows] = csvRows(input);
if (!header) return { contacts: [], errors: [] };
const col = new Map(header.map((h, i) => [h.trim().toLowerCase(), i]));
if (!col.has('name'))
return { contacts: [], errors: ['The first row must name the columns, with a "name" column'] };
const contacts: ContactData[] = [];
const errors: string[] = [];
rows.forEach((r, i) => {
if (!r.some((c) => c.trim())) return;
const get = (k: string) => {
const at = col.get(k);
return at === undefined ? '' : (r[at] ?? '').trim();
};
const numbers: ContactData['numbers'] = [];
for (let n = 1; col.has(`number${n}`); n++)
if (get(`number${n}`)) numbers.push({ label: get(`label${n}`), number: get(`number${n}`) });
const name = get('name');
if (!name) {
errors.push(`Row ${i + 2}: no name, skipped`);
return;
}
contacts.push({
name,
company: get('company') || null,
email: get('email') || null,
numbers,
notes: get('notes') || null,
});
});
return { contacts, errors };
}
+157
View File
@@ -0,0 +1,157 @@
// SPDX-License-Identifier: AGPL-3.0-or-later
// C1: vCard and CSV imports read what phones and address books export (11 §3.1).
import { describe, expect, it } from 'vitest';
import { parseCsv } from './csv.ts';
import { parseVcards } from './vcard.ts';
const IPHONE = [
'BEGIN:VCARD',
'VERSION:3.0',
'PRODID:-//Apple Inc.//iPhone OS 17.0//EN',
'N:Doe;Jane;;;',
'FN:Jane Doe',
'ORG:Acme Corp;',
'EMAIL;type=INTERNET;type=HOME;type=pref:jane@example.com',
'TEL;type=CELL;type=VOICE;type=pref:(312) 555-1234',
'item1.TEL:+1 312 555 0000',
'item1.X-ABLabel:_$!<Main>!$_',
'NOTE:Met at the fair\\, 2026\\nCall after 5',
'PHOTO;ENCODING=b;TYPE=JPEG:/9j/4AAQSkZJRgABAQAAAQABAAD',
' /2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJ',
'END:VCARD',
].join('\r\n');
const GOOGLE = `BEGIN:VCARD
VERSION:3.0
FN:Bob Smith
N:Smith;Bob;;;
TEL;TYPE=WORK:+13125559999
TEL;TYPE=HOME:3125558888
EMAIL;TYPE=INTERNET:bob@example.com
ORG:Widgets Inc.
item1.URL:http\\://example.com
END:VCARD
BEGIN:VCARD
VERSION:3.0
N:;;;;
TEL;TYPE=CELL:3125550101
END:VCARD
`;
const V21 = `BEGIN:VCARD
VERSION:2.1
N;CHARSET=UTF-8;ENCODING=QUOTED-PRINTABLE:M=C3=BCller;J=C3=BCrgen;;Dr.;
TEL;CELL:+49301234567
TEL;WORK;FAX:+49301234500
NOTE;ENCODING=QUOTED-PRINTABLE:Line one=0D=0ALine tw=
o
END:VCARD`;
const V40 = `BEGIN:VCARD
VERSION:4.0
FN:Carol Lee
TEL;VALUE=uri;TYPE="voice,cell":tel:+1-312-555-7777
END:VCARD
BEGIN:VCARD
VERSION:4.0
NOTE:nothing to call
END:VCARD`;
describe('parseVcards', () => {
it('reads an iPhone export: names, company, labels, note; skips the photo', () => {
expect(parseVcards(IPHONE)).toEqual({
contacts: [
{
name: 'Jane Doe',
company: 'Acme Corp',
email: 'jane@example.com',
numbers: [
{ label: 'mobile', number: '(312) 555-1234' },
{ label: 'main', number: '+1 312 555 0000' },
],
notes: 'Met at the fair, 2026\nCall after 5',
},
],
errors: [],
});
});
it('reads a Google export, and names a card with only a number after it', () => {
const { contacts } = parseVcards(GOOGLE);
expect(contacts.map((c) => [c.name, c.company, c.numbers])).toEqual([
[
'Bob Smith',
'Widgets Inc.',
[
{ label: 'work', number: '+13125559999' },
{ label: 'home', number: '3125558888' },
],
],
['3125550101', null, [{ label: 'mobile', number: '3125550101' }]],
]);
});
it('reads vCard 2.1: quoted-printable UTF-8, bare types, soft line breaks', () => {
const [c] = parseVcards(V21).contacts;
expect(c).toMatchObject({
name: 'Dr. Jürgen Müller',
numbers: [
{ label: 'mobile', number: '+49301234567' },
{ label: 'fax', number: '+49301234500' },
],
notes: 'Line one\r\nLine two',
});
});
it('reads vCard 4.0 tel: URIs, and reports a card with nothing to call', () => {
expect(parseVcards(V40)).toEqual({
contacts: [
{
name: 'Carol Lee',
company: null,
email: null,
numbers: [{ label: 'mobile', number: '+1-312-555-7777' }],
notes: null,
},
],
errors: ['Card 2: no name or number, skipped'],
});
});
});
describe('parseCsv', () => {
it('reads the 04 §7.4 columns in any order, with quotes and line breaks', () => {
const csv =
'Number1,Name,label1,company,notes,number2,label2\r\n' +
'312-555-1234,"Doe, Jane",mobile,Acme,"two\nlines",,\r\n' +
',,,,,,\r\n' +
'3125550000,,work,,,,\r\n' +
'+44 20 7946 0958,"Bob ""B"" Smith",,,,101,desk\r\n';
expect(parseCsv(csv)).toEqual({
contacts: [
{
name: 'Doe, Jane',
company: 'Acme',
email: null,
numbers: [{ label: 'mobile', number: '312-555-1234' }],
notes: 'two\nlines',
},
{
name: 'Bob "B" Smith',
company: null,
email: null,
numbers: [
{ label: '', number: '+44 20 7946 0958' },
{ label: 'desk', number: '101' },
],
notes: null,
},
],
errors: ['Row 4: no name, skipped'],
});
});
it('needs a header with a name column', () => {
expect(parseCsv('Jane,3125551234\n').errors[0]).toMatch(/"name" column/);
});
});
+149
View File
@@ -0,0 +1,149 @@
// SPDX-License-Identifier: AGPL-3.0-or-later
// vCard 2.1, 3.0 and 4.0 to contacts (11 §3.1): the name, company, first email, every phone and
// the note. Everything else (photos, addresses, birthdays) is ignored.
import type { ContactData } from '@selfphoneng/shared';
type Prop = { group: string; name: string; params: Map<string, string[]>; value: string };
/** "ENCODING=QUOTED-PRINTABLE;CHARSET=utf-8;TYPE=CELL,VOICE;WORK" (2.1 allows bare types). */
function parseParams(parts: string[]): Map<string, string[]> {
const out = new Map<string, string[]>();
for (const p of parts) {
const eq = p.indexOf('=');
const key = eq < 0 ? 'TYPE' : p.slice(0, eq).toUpperCase();
const raw = eq < 0 ? p : p.slice(eq + 1);
const vals = raw.replace(/"/g, '').split(',').filter(Boolean);
// 2.1's bare QUOTED-PRINTABLE is an encoding, not a type.
const k = eq < 0 && /^(QUOTED-PRINTABLE|BASE64|8BIT)$/i.test(raw) ? 'ENCODING' : key;
out.set(k, [...(out.get(k) ?? []), ...vals.map((v) => v.toUpperCase())]);
}
return out;
}
/** "[group.]NAME[;params]:value", with ':' allowed inside quoted params. */
function parseLine(line: string): Prop | null {
let quoted = false;
let colon = -1;
for (let i = 0; i < line.length; i++) {
if (line[i] === '"') quoted = !quoted;
else if (line[i] === ':' && !quoted) {
colon = i;
break;
}
}
if (colon < 0) return null;
const [head = '', ...params] = line.slice(0, colon).split(';');
const dot = head.lastIndexOf('.');
return {
group: dot < 0 ? '' : head.slice(0, dot).toUpperCase(),
name: head.slice(dot + 1).toUpperCase(),
params: parseParams(params),
value: line.slice(colon + 1),
};
}
function decodeQp(v: string, charset: string): string {
const bytes: number[] = [];
for (let i = 0; i < v.length; i++) {
const hex = v.slice(i + 1, i + 3);
if (v[i] === '=' && /^[0-9A-F]{2}$/i.test(hex)) {
bytes.push(parseInt(hex, 16));
i += 2;
} else bytes.push(v.charCodeAt(i) & 0xff);
}
try {
return new TextDecoder(charset).decode(new Uint8Array(bytes));
} catch {
return new TextDecoder('utf-8').decode(new Uint8Array(bytes));
}
}
/** Splits on unescaped `sep`, then unescapes \n \, \; \\. */
function components(v: string, sep: ';' | ','): string[] {
const out = [''];
for (let i = 0; i < v.length; i++) {
const c = v[i]!;
if (c === '\\' && i + 1 < v.length) {
const n = v[++i]!;
out[out.length - 1] += n === 'n' || n === 'N' ? '\n' : n;
} else if (c === sep) out.push('');
else out[out.length - 1] += c;
}
return out.map((s) => s.trim());
}
const text = (v: string) => components(v, ';').join(';').trim();
/** cell → mobile, work, home, fax, else other; an Apple X-ABLabel wins. */
function telLabel(types: string[], abLabel: string | undefined): string {
if (abLabel) {
const l = abLabel.replace(/^_\$!<|>!\$_$/g, '').trim();
if (l) return l.toLowerCase() === 'cell' ? 'mobile' : l.toLowerCase();
}
if (types.includes('FAX')) return 'fax';
if (types.some((t) => t === 'CELL' || t === 'MOBILE' || t === 'IPHONE')) return 'mobile';
if (types.includes('WORK')) return 'work';
if (types.includes('HOME')) return 'home';
if (types.includes('MAIN')) return 'main';
return 'other';
}
/** Every card in the text, in order. A card with no name, company or number is an error. */
export function parseVcards(input: string): { contacts: ContactData[]; errors: string[] } {
// Unfold: a line starting with a space or tab continues the one before (and 2.1
// quoted-printable continues a line that ends with "=").
const lines: string[] = [];
for (const l of input.replace(/^\uFEFF/, '').split(/\r\n|\r|\n/)) {
const prev = lines.at(-1);
if (prev?.endsWith('=') && /QUOTED-PRINTABLE/i.test(prev.split(':')[0]!))
lines[lines.length - 1] = prev.slice(0, -1) + l.replace(/^[ \t]/, '');
else if (prev !== undefined && /^[ \t]/.test(l)) lines[lines.length - 1] = prev + l.slice(1);
else lines.push(l);
}
const contacts: ContactData[] = [];
const errors: string[] = [];
let card: Prop[] | null = null;
for (const line of lines) {
const p = parseLine(line);
if (!p) continue;
if (p.name === 'BEGIN' && p.value.toUpperCase() === 'VCARD') card = [];
else if (p.name === 'END' && p.value.toUpperCase() === 'VCARD' && card) {
const c = toContact(card);
if (c) contacts.push(c);
else errors.push(`Card ${contacts.length + errors.length + 1}: no name or number, skipped`);
card = null;
} else if (card) {
const enc = p.params.get('ENCODING') ?? [];
if (enc.includes('QUOTED-PRINTABLE'))
p.value = decodeQp(p.value, p.params.get('CHARSET')?.[0]?.toLowerCase() ?? 'utf-8');
card.push(p);
}
}
return { contacts, errors };
}
function toContact(props: Prop[]): ContactData | null {
const first = (n: string) => props.find((p) => p.name === n)?.value;
const fn = first('FN') ? text(first('FN')!) : '';
const n = first('N');
const [family = '', given = '', middle = '', prefix = '', suffix = ''] = n
? components(n, ';')
: [];
const fromN = [prefix, given, middle, family, suffix].filter(Boolean).join(' ');
const org = first('ORG') ? components(first('ORG')!, ';')[0] || null : null;
const email = first('EMAIL') ? text(first('EMAIL')!) || null : null;
const abLabels = new Map(
props.filter((p) => p.name === 'X-ABLABEL' && p.group).map((p) => [p.group, text(p.value)]),
);
const numbers = props
.filter((p) => p.name === 'TEL')
.map((p) => ({
label: telLabel(p.params.get('TYPE') ?? [], p.group ? abLabels.get(p.group) : undefined),
number: text(p.value).replace(/^tel:/i, '').split(';')[0]!.trim(),
}))
.filter((t) => t.number);
const note = first('NOTE') ? text(first('NOTE')!) || null : null;
const name = fn || fromN || org || numbers[0]?.number;
if (!name) return null;
return { name, company: org, email, numbers, notes: note };
}