@installagent/sdk 0.15.0 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -8,6 +8,7 @@ import { DOCS_SEARCH_TOKEN_ENV, DOCS_SESSION_ENV } from "./docs-search.js";
8
8
  import { FATHOM_API_KEY_ENV } from "./fathom-webhook.js";
9
9
  import { LINEAR_API_TOKEN_ENV } from "./linear-project.js";
10
10
  import { PORTAL_ADMIN_SECRET_ENV } from "./portal-admin.js";
11
+ import { PREP_CALENDAR_ID_ENV } from "./tech-call-prep.js";
11
12
  /** Day-one shared secrets — every technician gets read access. */
12
13
  export const DEFAULT_TECH_VAULT = "team-techs";
13
14
  /** Payments / DB / deploy secrets — granted case-by-case. */
@@ -132,18 +133,31 @@ export const ENV_VARS = [
132
133
  source: "vault",
133
134
  doctor: true,
134
135
  vault: DEFAULT_TECH_VAULT,
135
- neededBy: "ia client-drive, ia triage",
136
+ neededBy: "ia client-drive, ia triage, ia tech-call prep",
136
137
  howToGet: `the Drive service-account key JSON — ${inTechVault}`,
137
138
  section: SECTION_DRIVERS,
138
139
  comment: "the Drive service-account key JSON, single line — filled by `ia env fill`",
139
140
  },
141
+ {
142
+ // The calendar that holds the client calls. An id, not a secret: each
143
+ // person sets their own. The calendar must be shared read-only with the
144
+ // Drive service account, or the invite check reports "not checked".
145
+ name: PREP_CALENDAR_ID_ENV,
146
+ tier: "optional",
147
+ source: "personal",
148
+ doctor: false,
149
+ neededBy: "ia tech-call prep (the invite check)",
150
+ howToGet: "the calendar id (Google Calendar → Settings → Integrate calendar), after you share that calendar read-only with the Drive service account",
151
+ section: SECTION_DRIVERS,
152
+ comment: "optional — the calendar id for `ia tech-call prep`. Share the calendar read-only\nwith the Drive service account first; unset = the invite check is not run.",
153
+ },
140
154
  {
141
155
  name: FATHOM_API_KEY_ENV,
142
156
  tier: "optional",
143
157
  source: "vault",
144
158
  doctor: true,
145
159
  vault: DEFAULT_TECH_VAULT,
146
- neededBy: "ia secrets mint fathom-webhook",
160
+ neededBy: "ia secrets mint fathom-webhook, ia tech-call verify / update-pass (transcript fallback)",
147
161
  howToGet: `the Fathom account API key — ${inTechVault}`,
148
162
  section: SECTION_DRIVERS,
149
163
  comment: "Fathom dashboard → Settings → API Access — filled by `ia env fill`",
@@ -187,7 +201,7 @@ export const ENV_VARS = [
187
201
  source: "vault",
188
202
  doctor: false,
189
203
  vault: DEFAULT_TECH_VAULT,
190
- neededBy: "ia build-estimate, ia secrets mint gemini-api-key",
204
+ neededBy: "ia build-estimate, ia tech-call verify / update-pass, ia secrets mint gemini-api-key",
191
205
  howToGet: inTechVault,
192
206
  section: SECTION_DRIVERS,
193
207
  },
@@ -268,6 +282,8 @@ const TECH_ROLE_VAR_NAMES = new Set([
268
282
  N8N_API_URL_ENV,
269
283
  N8N_API_KEY_ENV,
270
284
  GEMINI_API_KEY_ENV,
285
+ // Personal, optional: the calendar id for `ia tech-call prep` (2026-11-19).
286
+ PREP_CALENDAR_ID_ENV,
271
287
  // Every technician's `ia hours-export` sends with it (2026-09-24).
272
288
  HOURS_EXPORT_SECRET_ENV,
273
289
  // In team-techs by the account owner's choice (2026-09-24); no `ia` command reads them.
package/dist/index.d.ts CHANGED
@@ -48,6 +48,11 @@ export { type OnboardingChange, type OnboardingRetirePlan, planOnboardingRetire,
48
48
  export { type StandupCallPrep, type StandupCallPrepStatus, type StandupGitState, type StandupIssueRef, type StandupLinear, type StandupOptions, type StandupRepo, type StandupRepoLint, type StandupResult, type StandupStaleTodo, standup, } from "./standup.js";
49
49
  export { type SyncRepoResult, type SyncRepoStatus, type SyncReposOptions, type SyncReposResult, syncRepos, workspaceRepoNames, } from "./sync-repos.js";
50
50
  export { type SyncTemplatesFileResult, type SyncTemplatesFileStatus, type SyncTemplatesOptions, type SyncTemplatesResult, syncTemplates, TEMPLATE_CLAUDE_SETTINGS, TEMPLATE_ROOT_DOCS, } from "./sync-templates.js";
51
+ export { AGENDA_API_PATH, AGENDA_FILE, agendaFileContent, prepGapsBlock, type TechCallAgendaAnswer, type TechCallAgendaOptions, type TechCallAgendaResult, techCallAgenda, } from "./tech-call-agenda.js";
52
+ export { NOTE_LANDED_PATH, type NoteLandedAnswer, type NoteLandedEvent, parseNoteFrontmatter, type TechCallNoteLandedOptions, type TechCallNoteLandedResult, techCallNoteLanded, } from "./tech-call-note-landed.js";
53
+ export { checkAgendaDoc, checkAgendaFile, checkDocs, checkInvite, checkLinear, checkPortalOrg, checkScaffold, checkVault, MANUAL_PREP, PREP_CALENDAR_ID_ENV, type PrepCalendarEvent, type PrepCheck, type PrepProbes, type PrepRepoFiles, type PrepStatus, type PrepTeam, renderPrepBlock, type TechCallPrepOptions, type TechCallPrepResult, techCallPrep, withPrepBlock, } from "./tech-call-prep.js";
54
+ export { buildUpdatePrompt, type ChangeKind, checkChanges, checkGates, checkLinearDrafts, FALLBACK_SLACK_USER_ENV, type GateFailure, handEditedLines, type LinearDraft, renderUpdateEvidence, type TechCallUpdatePassOptions, type TechCallUpdatePassResult, techCallUpdatePass, UPDATE_PASS_ALLOWED, UPDATE_PASS_MODEL, type UpdateChange, type UpdatePassStatus, updatePassNotice, } from "./tech-call-update-pass.js";
55
+ export { applyMarks, buildVerifyPrompt, type CallTranscript, type ClaimKind, type ClaimVerdict, checkClaims, checkPromises, findQuote, NoTranscriptError, renderVerifyEvidence, stripMarks, type TechCallVerifyOptions, type TechCallVerifyResult, techCallVerify, VERIFY_DOCS, VERIFY_MODEL, type VerifyClaim, type VerifyPromise, type VerifySources, } from "./tech-call-verify.js";
51
56
  export { adhocReason, selectClientSlugs, TEMPLATE_RETIRED_FILES, TEMPLATE_SYNCED_FILES, type TemplateSyncFileResult, type TemplateSyncFileStatus, type TemplateSyncOptions, type TemplateSyncRepoResult, type TemplateSyncResult, templateSync, } from "./template-sync.js";
52
57
  export { TRIAGE_BACKFILL_CHUNK, type TriageBackfillOptions, type TriageBackfillResult, triageBackfill, } from "./triage-backfill.js";
53
58
  export { checkTriageRecordWiring, detectWorkflowProvider, PORTAL_INGEST_CREDENTIAL_NAME, TRIAGE_RECORDS_PATH, type TriageEnableOptions, type TriageEnableResult, type TriageWiringCheck, type TriageWiringCheckId, type TriageWiringReport, triageEnable, } from "./triage-enable.js";
package/dist/index.js CHANGED
@@ -51,6 +51,11 @@ export { planOnboardingRetire, ROADMAP_ARCHIVE, ROADMAP_FILE, roadmapRetire, } f
51
51
  export { standup, } from "./standup.js";
52
52
  export { syncRepos, workspaceRepoNames, } from "./sync-repos.js";
53
53
  export { syncTemplates, TEMPLATE_CLAUDE_SETTINGS, TEMPLATE_ROOT_DOCS, } from "./sync-templates.js";
54
+ export { AGENDA_API_PATH, AGENDA_FILE, agendaFileContent, prepGapsBlock, techCallAgenda, } from "./tech-call-agenda.js";
55
+ export { NOTE_LANDED_PATH, parseNoteFrontmatter, techCallNoteLanded, } from "./tech-call-note-landed.js";
56
+ export { checkAgendaDoc, checkAgendaFile, checkDocs, checkInvite, checkLinear, checkPortalOrg, checkScaffold, checkVault, MANUAL_PREP, PREP_CALENDAR_ID_ENV, renderPrepBlock, techCallPrep, withPrepBlock, } from "./tech-call-prep.js";
57
+ export { buildUpdatePrompt, checkChanges, checkGates, checkLinearDrafts, FALLBACK_SLACK_USER_ENV, handEditedLines, renderUpdateEvidence, techCallUpdatePass, UPDATE_PASS_ALLOWED, UPDATE_PASS_MODEL, updatePassNotice, } from "./tech-call-update-pass.js";
58
+ export { applyMarks, buildVerifyPrompt, checkClaims, checkPromises, findQuote, NoTranscriptError, renderVerifyEvidence, stripMarks, techCallVerify, VERIFY_DOCS, VERIFY_MODEL, } from "./tech-call-verify.js";
54
59
  export { adhocReason, selectClientSlugs, TEMPLATE_RETIRED_FILES, TEMPLATE_SYNCED_FILES, templateSync, } from "./template-sync.js";
55
60
  export { TRIAGE_BACKFILL_CHUNK, triageBackfill, } from "./triage-backfill.js";
56
61
  export { checkTriageRecordWiring, detectWorkflowProvider, PORTAL_INGEST_CREDENTIAL_NAME, TRIAGE_RECORDS_PATH, triageEnable, } from "./triage-enable.js";
@@ -0,0 +1,57 @@
1
+ export declare const AGENDA_API_PATH = "/api/admin/agenda";
2
+ export declare const AGENDA_FILE = "docs/05-call-agenda.md";
3
+ export declare const PREP_GAPS_START = "<!-- PREP_GAPS:START -->";
4
+ export declare const PREP_GAPS_END = "<!-- PREP_GAPS:END -->";
5
+ /** The portal's answer (portal `lib/agenda-service.ts` → `AgendaResult`). */
6
+ export interface TechCallAgendaAnswer {
7
+ slug: string;
8
+ markdown: string;
9
+ callDate: string;
10
+ callDateKnown: boolean;
11
+ playbook: string | null;
12
+ notes: "registry" | "fathom";
13
+ repoDocs: boolean;
14
+ scriptLoaded: boolean;
15
+ warnings: string[];
16
+ doc: {
17
+ action: "created" | "updated";
18
+ id: string;
19
+ name: string;
20
+ webViewLink: string | null;
21
+ previousName?: string;
22
+ } | null;
23
+ stale: string[];
24
+ }
25
+ export interface TechCallAgendaOptions {
26
+ /** installagent/ workspace root (holds clients/client-<slug>/). Needed for `write`. */
27
+ workspaceDir: string;
28
+ /** YYYY-MM-DD of the call. Omitted = the portal uses today and the agenda says so. */
29
+ callDate?: string;
30
+ /** Update (or create) the ONE agenda Doc in the client's Drive folder. */
31
+ publish?: boolean;
32
+ /** Write docs/05-call-agenda.md in the client checkout. */
33
+ write?: boolean;
34
+ secret?: string;
35
+ baseUrl?: string;
36
+ fetchImpl?: typeof fetch;
37
+ }
38
+ export interface TechCallAgendaResult {
39
+ answer: TechCallAgendaAnswer;
40
+ /** Absolute path of the file written, or null. */
41
+ written: string | null;
42
+ /** True when an existing prep-gaps block was carried into the new file. */
43
+ keptPrepGaps: boolean;
44
+ }
45
+ /** The text between the prep-gaps markers (markers excluded), or null. */
46
+ export declare function prepGapsBlock(markdown: string): string | null;
47
+ /**
48
+ * The portal's agenda → the repo file: the `Type: spec` line under the title
49
+ * (repo-lint rule 19; a repo convention, so the Drive Doc has none), and the
50
+ * prep-gaps block of the file on disk kept — `ia tech-call prep` wrote it, and
51
+ * a new draft must not throw its findings away.
52
+ */
53
+ export declare function agendaFileContent(markdown: string, existing: string | null): {
54
+ content: string;
55
+ keptPrepGaps: boolean;
56
+ };
57
+ export declare function techCallAgenda(slug: string, options: TechCallAgendaOptions): Promise<TechCallAgendaResult>;
@@ -0,0 +1,94 @@
1
+ // `ia tech-call agenda <slug>` — the ONE tech-call agenda. The portal drafts
2
+ // it (POST /api/admin/agenda: call notes + transcript, the build repo's
3
+ // engagement docs, the industry playbook, the discovery-call script) — the
4
+ // same code the lead-close kickoff runs — and this command is how a technician
5
+ // regenerates it before the call.
6
+ //
7
+ // Default = draft only: the markdown comes back and nothing is written
8
+ // anywhere. `publish` puts it in the ONE agenda Doc of the call in the
9
+ // client's Drive folder (updated in place; other agenda Docs are reported as
10
+ // stale, never deleted). `write` puts the same text in the client checkout's
11
+ // docs/05-call-agenda.md (working tree only — never a commit).
12
+ //
13
+ // `publish` changes a client's Drive folder, so this ships as SDK + CLI only
14
+ // (golden rule 2). No agenda logic lives here: one implementation, in the portal.
15
+ import { existsSync } from "node:fs";
16
+ import { readFile, writeFile } from "node:fs/promises";
17
+ import { join, resolve } from "node:path";
18
+ import { SLUG_PATTERN } from "./new-client.js";
19
+ import { DEFAULT_PORTAL_URL, PORTAL_ADMIN_SECRET_ENV, PORTAL_URL_ENV, PortalAdminAuthError, PortalRequestError, } from "./portal-admin.js";
20
+ export const AGENDA_API_PATH = "/api/admin/agenda";
21
+ export const AGENDA_FILE = "docs/05-call-agenda.md";
22
+ export const PREP_GAPS_START = "<!-- PREP_GAPS:START -->";
23
+ export const PREP_GAPS_END = "<!-- PREP_GAPS:END -->";
24
+ /** The text between the prep-gaps markers (markers excluded), or null. */
25
+ export function prepGapsBlock(markdown) {
26
+ const start = markdown.indexOf(PREP_GAPS_START);
27
+ const end = markdown.indexOf(PREP_GAPS_END);
28
+ if (start === -1 || end === -1 || end < start)
29
+ return null;
30
+ return markdown.slice(start + PREP_GAPS_START.length, end);
31
+ }
32
+ /**
33
+ * The portal's agenda → the repo file: the `Type: spec` line under the title
34
+ * (repo-lint rule 19; a repo convention, so the Drive Doc has none), and the
35
+ * prep-gaps block of the file on disk kept — `ia tech-call prep` wrote it, and
36
+ * a new draft must not throw its findings away.
37
+ */
38
+ export function agendaFileContent(markdown, existing) {
39
+ const lines = markdown.replace(/\r\n/g, "\n").split("\n");
40
+ if (lines[0]?.startsWith("# ") && lines[1]?.trim() !== "Type: spec") {
41
+ lines.splice(1, 0, "Type: spec");
42
+ }
43
+ let content = lines.join("\n");
44
+ const kept = existing ? prepGapsBlock(existing) : null;
45
+ const fresh = prepGapsBlock(content);
46
+ let keptPrepGaps = false;
47
+ if (kept !== null && fresh !== null && kept.trim() && kept !== fresh) {
48
+ content = content.replace(`${PREP_GAPS_START}${fresh}${PREP_GAPS_END}`, `${PREP_GAPS_START}${kept}${PREP_GAPS_END}`);
49
+ keptPrepGaps = true;
50
+ }
51
+ return { content: content.endsWith("\n") ? content : `${content}\n`, keptPrepGaps };
52
+ }
53
+ export async function techCallAgenda(slug, options) {
54
+ if (!SLUG_PATTERN.test(slug)) {
55
+ throw new Error(`invalid slug "${slug}" — use lowercase letters, digits, and hyphens`);
56
+ }
57
+ if (options.callDate && !/^\d{4}-\d{2}-\d{2}$/.test(options.callDate)) {
58
+ throw new Error(`--call-date must be YYYY-MM-DD, not "${options.callDate}"`);
59
+ }
60
+ const repoDir = join(resolve(options.workspaceDir), "clients", `client-${slug}`);
61
+ // Checked BEFORE the model call: a draft nobody can write is a wasted run.
62
+ if (options.write && !existsSync(join(repoDir, "docs"))) {
63
+ throw new Error(`${join(repoDir, "docs")} not found — clone the client repo first (\`ia sync\`), or drop --write`);
64
+ }
65
+ const secret = options.secret ?? process.env[PORTAL_ADMIN_SECRET_ENV];
66
+ if (!secret) {
67
+ throw new PortalAdminAuthError(`portal admin secret required — set ${PORTAL_ADMIN_SECRET_ENV} (from 1Password; \`ia env fill\`)`);
68
+ }
69
+ const baseUrl = (options.baseUrl ?? process.env[PORTAL_URL_ENV] ?? DEFAULT_PORTAL_URL).replace(/\/$/, "");
70
+ const res = await (options.fetchImpl ?? fetch)(`${baseUrl}${AGENDA_API_PATH}`, {
71
+ method: "POST",
72
+ headers: { Authorization: `Bearer ${secret}`, "Content-Type": "application/json" },
73
+ body: JSON.stringify({
74
+ slug,
75
+ ...(options.callDate ? { callDate: options.callDate } : {}),
76
+ publish: options.publish === true,
77
+ }),
78
+ });
79
+ if (res.status === 401) {
80
+ throw new PortalAdminAuthError(`the portal refused the secret (HTTP 401) — check ${PORTAL_ADMIN_SECRET_ENV}`);
81
+ }
82
+ const body = (await res.json().catch(() => null));
83
+ if (!res.ok || !body?.markdown) {
84
+ const serverError = body?.error ?? null;
85
+ throw new PortalRequestError(`agenda failed (HTTP ${res.status})${serverError ? `: ${serverError}` : ""}`, res.status, serverError);
86
+ }
87
+ if (!options.write)
88
+ return { answer: body, written: null, keptPrepGaps: false };
89
+ const target = join(repoDir, AGENDA_FILE);
90
+ const existing = existsSync(target) ? await readFile(target, "utf8") : null;
91
+ const file = agendaFileContent(body.markdown, existing);
92
+ await writeFile(target, file.content);
93
+ return { answer: body, written: target, keptPrepGaps: file.keptPrepGaps };
94
+ }
@@ -0,0 +1,43 @@
1
+ export declare const NOTE_LANDED_PATH = "/api/hooks/note-landed";
2
+ export interface NoteLandedEvent {
3
+ slug: string;
4
+ /** Filename inside `clients/<slug>/calls/`. */
5
+ file: string;
6
+ date: string;
7
+ /** The note's frontmatter `type`, lower-cased. */
8
+ type: string;
9
+ fathomId?: string;
10
+ }
11
+ /** The portal's answer (portal `lib/note-landed.ts` → `NoteLandedDecision`, plus the run mode). */
12
+ export interface NoteLandedAnswer {
13
+ mode: string;
14
+ kickoff: "found" | "none";
15
+ action: "docs-rerun" | "update-pass" | "none";
16
+ steps: string[];
17
+ ran: string[];
18
+ reason: string;
19
+ key: string;
20
+ }
21
+ export interface TechCallNoteLandedOptions {
22
+ /** installagent/ workspace root (holds team-clients/). */
23
+ workspaceDir: string;
24
+ /** Note filename inside calls/; default = the newest note. */
25
+ file?: string;
26
+ /** Build and return the event; send nothing. */
27
+ dryRun?: boolean;
28
+ /** Bearer secret; defaults to $IA_PORTAL_ADMIN_SECRET. */
29
+ secret?: string;
30
+ /** Portal base URL; defaults to $IA_PORTAL_URL, then the prod portal. */
31
+ baseUrl?: string;
32
+ /** Injectable for tests; defaults to global fetch. */
33
+ fetchImpl?: typeof fetch;
34
+ }
35
+ export interface TechCallNoteLandedResult {
36
+ event: NoteLandedEvent;
37
+ sent: boolean;
38
+ /** Absent on a dry run. */
39
+ answer?: NoteLandedAnswer;
40
+ }
41
+ /** Top-level `key: value` pairs of a note's YAML frontmatter, quotes stripped. */
42
+ export declare function parseNoteFrontmatter(content: string): Record<string, string>;
43
+ export declare function techCallNoteLanded(slug: string, options: TechCallNoteLandedOptions): Promise<TechCallNoteLandedResult>;
@@ -0,0 +1,93 @@
1
+ // `ia tech-call note-landed <slug>` — replay the "note landed" event for one
2
+ // call note in the local team-clients checkout. The normal sender is
3
+ // team-clients' call-note-landed GitHub Actions workflow (a note reaches
4
+ // main); this is the same event sent by hand, for a note the workflow missed
5
+ // or a portal answer worth seeing again.
6
+ //
7
+ // It POSTs to the portal's /api/hooks/note-landed with the admin secret the
8
+ // `ia portal` commands already use. It sends the slug, the file name and
9
+ // four frontmatter values — never note content. It reads the registry and
10
+ // never writes to it (golden rule 7). What the portal does with the event is
11
+ // the portal's decision; its answer comes back verbatim.
12
+ //
13
+ // The portal may re-run kickoff steps on this event (a client-facing
14
+ // mutation), so this ships as SDK + CLI only — no MCP twin (golden rule 2).
15
+ import { existsSync } from "node:fs";
16
+ import { readdir, readFile } from "node:fs/promises";
17
+ import { join, resolve } from "node:path";
18
+ import { SLUG_PATTERN } from "./new-client.js";
19
+ import { DEFAULT_PORTAL_URL, PORTAL_ADMIN_SECRET_ENV, PORTAL_URL_ENV, PortalAdminAuthError, PortalRequestError, } from "./portal-admin.js";
20
+ export const NOTE_LANDED_PATH = "/api/hooks/note-landed";
21
+ /** `YYYY-MM-DD.md` or `YYYY-MM-DD-<hint>.md` — never README.md, never `*.transcript.md`. */
22
+ const NOTE_FILE = /^\d{4}-\d{2}-\d{2}(-[a-z0-9-]+)?\.md$/;
23
+ /** Top-level `key: value` pairs of a note's YAML frontmatter, quotes stripped. */
24
+ export function parseNoteFrontmatter(content) {
25
+ const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
26
+ const values = {};
27
+ if (!match?.[1])
28
+ return values;
29
+ for (const line of match[1].split(/\r?\n/)) {
30
+ const pair = /^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$/.exec(line);
31
+ if (!pair?.[1])
32
+ continue;
33
+ values[pair[1]] = (pair[2] ?? "").trim().replace(/^["'](.*)["']$/, "$1");
34
+ }
35
+ return values;
36
+ }
37
+ export async function techCallNoteLanded(slug, options) {
38
+ if (!SLUG_PATTERN.test(slug)) {
39
+ throw new Error(`invalid slug "${slug}" — use lowercase letters, digits, and hyphens`);
40
+ }
41
+ const callsDir = join(resolve(options.workspaceDir), "team-clients", "clients", slug, "calls");
42
+ if (!existsSync(callsDir)) {
43
+ throw new Error(`${callsDir} not found — clone team-clients (\`ia init\`) and check the slug is a registry folder`);
44
+ }
45
+ const notes = (await readdir(callsDir)).filter((name) => NOTE_FILE.test(name)).sort();
46
+ let file = options.file?.trim();
47
+ if (file) {
48
+ if (!NOTE_FILE.test(file)) {
49
+ throw new Error(`--file must be a call note name like 2026-11-18.md, not "${file}"`);
50
+ }
51
+ if (!notes.includes(file)) {
52
+ throw new Error(`no ${file} in clients/${slug}/calls/. Notes there: ${notes.join(", ") || "none"}`);
53
+ }
54
+ }
55
+ else {
56
+ file = notes.at(-1);
57
+ if (!file)
58
+ throw new Error(`clients/${slug}/calls/ has no call note yet`);
59
+ }
60
+ const fm = parseNoteFrontmatter(await readFile(join(callsDir, file), "utf8"));
61
+ const type = (fm.type ?? "").toLowerCase();
62
+ if (!type) {
63
+ throw new Error(`clients/${slug}/calls/${file} has no \`type\` in its frontmatter — the portal cannot route it`);
64
+ }
65
+ const event = {
66
+ slug,
67
+ file,
68
+ date: /^\d{4}-\d{2}-\d{2}$/.test(fm.date ?? "") ? fm.date : file.slice(0, 10),
69
+ type,
70
+ ...(fm.fathom_id ? { fathomId: fm.fathom_id } : {}),
71
+ };
72
+ if (options.dryRun)
73
+ return { event, sent: false };
74
+ const secret = options.secret ?? process.env[PORTAL_ADMIN_SECRET_ENV];
75
+ if (!secret) {
76
+ throw new PortalAdminAuthError(`portal admin secret required — set ${PORTAL_ADMIN_SECRET_ENV} (from 1Password; \`ia env fill\`)`);
77
+ }
78
+ const baseUrl = (options.baseUrl ?? process.env[PORTAL_URL_ENV] ?? DEFAULT_PORTAL_URL).replace(/\/$/, "");
79
+ const res = await (options.fetchImpl ?? fetch)(`${baseUrl}${NOTE_LANDED_PATH}`, {
80
+ method: "POST",
81
+ headers: { Authorization: `Bearer ${secret}`, "Content-Type": "application/json" },
82
+ body: JSON.stringify(event),
83
+ });
84
+ if (res.status === 401) {
85
+ throw new PortalAdminAuthError(`the portal refused the secret (HTTP 401) — check ${PORTAL_ADMIN_SECRET_ENV}`);
86
+ }
87
+ const body = (await res.json().catch(() => null));
88
+ if (!res.ok || !body) {
89
+ const serverError = body?.error ?? null;
90
+ throw new PortalRequestError(`note-landed failed (HTTP ${res.status})${serverError ? `: ${serverError}` : ""}`, res.status, serverError);
91
+ }
92
+ return { event, sent: true, answer: body };
93
+ }
@@ -0,0 +1,94 @@
1
+ import { type ExecFileFn } from "./exec.js";
2
+ export declare const PREP_CALENDAR_ID_ENV = "IA_PREP_CALENDAR_ID";
3
+ export declare const AGENDA_DOC_MARKER = "tech-discovery-agenda";
4
+ export declare const PORTAL_LOGIN_ITEM_TITLE = "Install Agent client portal";
5
+ export type PrepStatus = "pass" | "gap" | "skipped";
6
+ export interface PrepCheck {
7
+ id: string;
8
+ status: PrepStatus;
9
+ /** What was found, in one sentence. No email address, no secret. */
10
+ detail: string;
11
+ /** What to do about a gap or a skip. Empty on a pass. */
12
+ fix: string;
13
+ }
14
+ /** The people who must be on the invite, from the CRM. Names and emails stay in memory only. */
15
+ export interface PrepTeam {
16
+ technicians: Array<{
17
+ name: string;
18
+ email: string;
19
+ }>;
20
+ sales: Array<{
21
+ name: string;
22
+ email: string;
23
+ }>;
24
+ /** The client's company email domain, or "" for a free-mail contact. */
25
+ clientDomain: string;
26
+ }
27
+ export interface PrepCalendarEvent {
28
+ summary: string;
29
+ attendees: string[];
30
+ }
31
+ /**
32
+ * The outside lookups, one per system. Each returns its data, or a string =
33
+ * "could not run, and why" (the check is then `skipped`). Injectable for tests.
34
+ */
35
+ export interface PrepProbes {
36
+ team(slug: string): Promise<PrepTeam | string>;
37
+ calendarEvents(date: string): Promise<PrepCalendarEvent[] | string>;
38
+ vaultItemTitles(vault: string): Promise<string[] | string>;
39
+ portalOrgExists(slug: string): Promise<boolean | string>;
40
+ openLinearIssues(slug: string): Promise<string[] | string>;
41
+ driveDocTitles(slug: string): Promise<string[] | string>;
42
+ }
43
+ export interface PrepRepoFiles {
44
+ /** Top-level names in the client checkout. */
45
+ entries: string[];
46
+ onboardingHtml: string;
47
+ /** docs/ file name → text, for 01-04 and 05. */
48
+ docs: Record<string, string>;
49
+ /** evidence/ file name → text, transcript checks only. */
50
+ evidence: Record<string, string>;
51
+ /** Call notes in the registry, newest last: `2026-11-16`, `2026-11-18`. */
52
+ registryCalls: string[];
53
+ }
54
+ export declare function checkScaffold(files: PrepRepoFiles): PrepCheck;
55
+ export declare function checkDocs(files: PrepRepoFiles): PrepCheck[];
56
+ export declare function checkAgendaFile(files: PrepRepoFiles, callDate: string): PrepCheck;
57
+ export declare function checkInvite(events: PrepCalendarEvent[] | string, team: PrepTeam | string, callDate: string): PrepCheck;
58
+ export declare function checkVault(titles: string[] | string, vault: string): PrepCheck[];
59
+ export declare function checkPortalOrg(exists: boolean | string, slug: string): PrepCheck;
60
+ /** INS ids under `## Open questions...` of the tech spec. */
61
+ export declare function openQuestionIds(techSpec: string): string[];
62
+ export declare function checkLinear(open: string[] | string, techSpec: string): PrepCheck;
63
+ export declare function checkAgendaDoc(titles: string[] | string, callDate: string): PrepCheck;
64
+ /** What only a person can do. Fixed text, on every agenda. */
65
+ export declare const MANUAL_PREP: string[];
66
+ export declare function renderPrepBlock(checks: PrepCheck[], checkedOn: string): string;
67
+ /** docs/05 with its prep-gaps block replaced. Throws when the file has no block. */
68
+ export declare function withPrepBlock(agenda: string, block: string): string;
69
+ export declare function realProbes(options: {
70
+ workspaceDir: string;
71
+ fetchImpl?: typeof fetch;
72
+ execFileImpl?: ExecFileFn;
73
+ env?: Record<string, string | undefined>;
74
+ }): PrepProbes;
75
+ export interface TechCallPrepOptions {
76
+ workspaceDir: string;
77
+ /** YYYY-MM-DD. Default: the date in the title of docs/05-call-agenda.md, else today. */
78
+ callDate?: string;
79
+ /** Replace the prep-gaps block of docs/05-call-agenda.md in the working tree. */
80
+ write?: boolean;
81
+ probes?: PrepProbes;
82
+ now?: Date;
83
+ }
84
+ export interface TechCallPrepResult {
85
+ slug: string;
86
+ callDate: string;
87
+ checks: PrepCheck[];
88
+ counts: Record<PrepStatus, number>;
89
+ /** The block text (between the markers). */
90
+ block: string;
91
+ /** Absolute path of docs/05-call-agenda.md when it was written, else null. */
92
+ written: string | null;
93
+ }
94
+ export declare function techCallPrep(slug: string, options: TechCallPrepOptions): Promise<TechCallPrepResult>;