@decibelsystems/tools 2.2.0-beta.0 → 3.1.0

package/dist/tools/zoom.d.ts

@@ -0,0 +1,234 @@
+export interface ZoomCredentials {
+    account_id: string;
+    client_id: string;
+    client_secret: string;
+}
+/** One entry from GET /meetings/meeting_summaries. Only the fields the port
+ *  actually reads are typed; Zoom sends more. */
+export interface MeetingSummary {
+    meeting_uuid?: string;
+    meeting_id?: number | string;
+    meeting_topic?: string;
+    meeting_start_time?: string;
+    summary_start_time?: string;
+    [key: string]: unknown;
+}
+/** GET /meetings/{uuid}/meeting_summary. Two shapes: the modern single
+ *  markdown blob, and a deprecated split. See renderSummary. */
+export interface MeetingDetail {
+    summary_content?: string;
+    summary_overview?: string;
+    summary_details?: Array<{
+        label?: string;
+        summary?: string;
+    }>;
+    next_steps?: unknown[];
+    [key: string]: unknown;
+}
+export interface ZoomRoute {
+    /** Decibel project id */
+    id: string;
+    /** Lowercased topic needles, longest first (see loadRoutes) */
+    match: string[];
+    /** Absolute output directory */
+    out: string;
+}
+export interface SyncOptions {
+    from?: string;
+    to?: string;
+    days?: number;
+    /** Single output directory. Ignored when route is true. */
+    out?: string;
+    /** Fan out across the project registry instead of one directory. */
+    route?: boolean;
+    /** Only topics containing this substring (case-insensitive). */
+    match?: string;
+    force?: boolean;
+    dryRun?: boolean;
+    status?: string;
+    noFrontmatter?: boolean;
+}
+export interface SyncResult {
+    from: string;
+    to: string;
+    returned: number;
+    in_range: number;
+    written: number;
+    skipped: number;
+    empty: number;
+    unrouted: number;
+    reclaimed: number;
+    dry_run: boolean;
+    routes?: Array<{
+        id: string;
+        match: string[];
+        out: string;
+    }>;
+    files: Array<{
+        name: string;
+        dest: string;
+        project: string | null;
+        action: string;
+    }>;
+    notes: string[];
+}
+export declare class ZoomError extends Error {
+    code: string;
+    hint?: string;
+    constructor(code: string, message: string, hint?: string);
+}
+/**
+ * Resolution order: environment, then the config.yaml `zoom` block, then the
+ * standalone JSON file, then the legacy path.
+ *
+ * The JSON file is where plasiv's credentials actually live today (mode 600),
+ * so it stays supported rather than being migrated out from under a working
+ * setup. config.yaml is the location EPIC-0036 asks for and is preferred for
+ * anything new — it is the same file the daemon already reads secrets from.
+ *
+ * Environment wins only when ALL THREE values are present. A half-set
+ * environment falling through to a complete file beats erroring on a partial
+ * override, and mixing the two sources produces an account_id from one Zoom app
+ * with a secret from another, which fails at the token call with a message that
+ * blames the wrong thing.
+ */
+export declare function loadCredentials(): ZoomCredentials;
+/**
+ * Server-to-Server OAuth. The original fetched one token per run and never
+ * looked at it again; S2S tokens last an hour, so a backfill long enough to
+ * matter outlives its own credential and dies partway through with a 401 that
+ * looks like a permissions problem. This caches with an expiry and refetches.
+ */
+export declare function getToken(creds: ZoomCredentials, now?: number): Promise<string>;
+/** Test seam, and the escape hatch after a credential change mid-process. */
+export declare function clearTokenCache(): void;
+export interface ApiGetDeps {
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * The original had no retry, no backoff, no 429 handling and no concurrency
+ * cap — a serial loop issuing one detail call per meeting. Its clean log proves
+ * nothing, because it has only ever run at hand-driven volume; an account-wide
+ * backfill is the first time this would meet a rate limit.
+ *
+ * Retries 429 and 5xx with exponential backoff, honouring Retry-After when Zoom
+ * sends one. 4xx other than 429 is not retried — a 401 or a 404 does not get
+ * better by asking again.
+ */
+export declare function apiGet<T>(urlPath: string, token: string, params?: Record<string, string | number>, deps?: ApiGetDeps): Promise<T>;
+/**
+ * Zoom requires meeting UUIDs to be DOUBLE URL-encoded when they start with "/"
+ * or contain "//", and single-encoded otherwise.
+ *
+ * UNVERIFIED AGAINST REAL DATA: none of the 26 files on the plasiv disk carry a
+ * uuid that triggers the double branch, so that path comes from Zoom's docs
+ * rather than from a case anyone here has seen. The single branch is confirmed —
+ * it produces the same %3D%3D that appears inside the task permalinks Zoom
+ * embeds in its own summary markdown.
+ */
+export declare function encodeMeetingUuid(uuid: string): string;
+/**
+ * The list envelope is documented as `summaries`. When that key is absent this
+ * falls back to whatever list-of-dicts the payload does carry and says so,
+ * because the failure mode being defended against is a silent zero-result run:
+ * an envelope rename would otherwise read as "no meetings", which is
+ * indistinguishable from a quiet week.
+ */
+export declare function extractSummaryList(payload: Record<string, unknown>, notes?: string[]): MeetingSummary[];
+export declare function listSummaries(token: string, from: string, to: string, notes?: string[], deps?: ApiGetDeps): Promise<MeetingSummary[]>;
+/**
+ * Zoom returns the whole summary as markdown in `summary_content` on modern
+ * accounts. The split fields are the deprecated shape.
+ *
+ * UNVERIFIED AGAINST REAL DATA: the split branch has never been exercised here.
+ * Every one of the 26 files on the plasiv disk orders its sections Quick recap,
+ * Next steps, per-person groups, Collaboration, Summary — and the split branch
+ * structurally cannot put next_steps second, because it appends them last. That
+ * ordering is the proof the account is on summary_content. The split branch
+ * below is written from Zoom's field names, not from anything observed, and is
+ * kept only so an older account degrades into readable output instead of an
+ * empty file.
+ */
+export declare function renderSummary(detail: MeetingDetail): string;
+export declare function startOf(summary: MeetingSummary): string;
+/**
+ * Zoom ignores from/to on the summaries list endpoint, so the window has to be
+ * enforced here or it is a lie. An entry with no start time is kept rather than
+ * dropped — a missing timestamp is a reason to look at it, not to hide it.
+ */
+export declare function inRange(summary: MeetingSummary, from: string, to: string): boolean;
+/** Five keys, same order, same spelling as the Python. The dedup index reads
+ *  meeting_uuid back out of this block, so the format is load-bearing. */
+export declare function buildFrontmatter(summary: MeetingSummary, status: string): string;
+/**
+ * "{topic} {YYYY-MM-DD HH_MM}Z.md", topic stripped of characters that are
+ * illegal in a filename on some filesystem or other. Verified against the real
+ * file in the unrouted bucket: this produces "Ben - Pete 2026-08-12 17_04Z.md".
+ */
+export declare function filenameFor(summary: MeetingSummary): string;
+export declare function unroutedDir(): string;
+/**
+ * Projects carrying a `zoom` block in the registry:
+ *
+ *   "zoom": { "match": ["plasiv"], "out": "meetings/raw" }
+ *
+ * Aliases are deliberately NOT matched. They are tool-call addresses — "dt",
+ * "dv" — and a two-letter needle matches almost any meeting title.
+ *
+ * Needles are sorted longest-first so routing is deterministic by specificity.
+ * The original took the first rule that matched in registry order, which means
+ * a project whose needle is a substring of another project's needle silently
+ * stole its meetings depending on file ordering.
+ */
+export declare function loadRoutes(): ZoomRoute[];
+export declare function routeFor(summary: MeetingSummary, routes: ZoomRoute[]): ZoomRoute | null;
+export interface KnownMeeting {
+    file: string;
+    uuid: string;
+}
+/**
+ * Index meeting_uuid out of the first 600 bytes of every .md in the given
+ * directories, keyed on uuid AND start time.
+ *
+ * Two deliberate departures from the original:
+ *
+ * 1. UUID ALONE IS NOT THE KEY. If Zoom reuses a uuid across occurrences of a
+ *    recurring meeting, a uuid-keyed index silently skips the second occurrence
+ *    as already-seen. Nobody has observed that here and the Python does not
+ *    defend against it; keying on uuid+start costs nothing and closes it.
+ *
+ * 2. THE UNROUTED BUCKET IS NOT INDEXED HERE. See reclaim handling in
+ *    syncMeetings — an unrouted entry is UNCLAIMED, not SEEN.
+ */
+export declare function indexKnownMeetings(dirs: string[]): Map<string, KnownMeeting>;
+export declare function dedupKey(uuid: string, start: string): string;
+/** The stub left in the unrouted bucket. Carries enough to see what is waiting
+ *  — and nothing else.
+ *
+ *  ISS-0123: a routed run does not merely READ non-client meetings, it WRITES
+ *  them. The bucket on the plasiv machine holds a personal two-person meeting
+ *  with its full body on disk, put there by a single hand-run. Storing a stub
+ *  keeps the "never silently dropped" guarantee without spilling the content of
+ *  every meeting in the account onto the filesystem as a side effect of pulling
+ *  client ones.
+ *
+ *  This is only safe BECAUSE the unrouted bucket is excluded from the dedup
+ *  index. A stub in a seen-index would satisfy dedup forever and the real body
+ *  would never arrive. Privacy stub and dedup fix are one change, not two. */
+export declare function buildUnroutedStub(summary: MeetingSummary): string;
+export interface SyncDeps extends ApiGetDeps {
+    credentials?: ZoomCredentials;
+    token?: string;
+    routes?: ZoomRoute[];
+    now?: Date;
+}
+/**
+ * Pull summaries and write them where they belong.
+ *
+ * The routed path is the interesting one and the least exercised — one manual
+ * run in its life — so it is written here from the spec rather than trusted
+ * from the source.
+ */
+export declare function syncMeetings(opts?: SyncOptions, deps?: SyncDeps): Promise<SyncResult>;
+//# sourceMappingURL=zoom.d.ts.map

package/dist/tools/zoom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zoom.d.ts","sourceRoot":"","sources":["../../src/tools/zoom.ts"],"names":[],"mappings":"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"}