@finbheara/archive-client 0.32.0 → 0.34.0

package/README.md

@@ -99,6 +99,8 @@ c.features;   // [{ feature: "dancers", state: "full" | "missing", missing: [...
 | `events` | `events.years` | 260 |
 | `upcoming.feises` | `upcoming.feises`, and the `next` of `feises.series` (null with the reason without it) | 285 |
 | `upcoming.fields`, `upcoming.entrants` | `upcoming.fields`, `upcoming.entrants` (285 and 290 carry the tables empty) | 291 |
+| `upcoming.fields.instance` | the `feis_instance_id` `upcoming.fields` carries; absent, never refused, without it | 320 |
+| `calendar` | `calendar.get`, `calendar.list` | 320 |
 | `tabs`, `panels` | `tabs.query`, `tabs.stream`; `panels.query` | 184 |
 | `feis-panels` | `feisPanels.query` | 260 |
 | `staff.adjudicators` | `staff.adjudicators` | 230 |
@@ -697,7 +699,8 @@ o.feises;    // [{ occurrence_id, occurrence_ids, name_printed, date_lo, date_hi
              //    feis_brand_id, feis_instance_id, series_basis, brand_candidates, captured_id, state }]
 const f = await rel.upcoming.fields({ state: "pending" });  // state, feis, field_id, from, to
 f.fields;    // [{ field_id, feis_id, source, host_id, competition_code, count_only, occurrence_id,
-             //    name_printed, date_lo, date_hi, year, feis_brand_id, comp, state, flags,
+             //    name_printed, date_lo, date_hi, year, feis_brand_id, feis_instance_id, comp,
+             //    state, flags,
              //    results_competitions, results_feis_ids, held_out, merged_into, version, versions,
              //    captured_date, sha256,
              //    limits, entrants, stated_rows, printed_total }]
@@ -712,7 +715,10 @@ d.departures; // [{ field_id, feis_id, occurrence_id, feis_brand_id, competition
 `upcoming.feises` is every occurrence of the cut's feis-index the release holds no results of:
 `upcoming` (dated on or after the cut's day) or `no-results` (before it), each with every
 platform's or calendar's listing (`hosts`) and its feis series where one was named (`series_basis`
-says how; `none` leaves `feis_brand_id` null, the unjoined ones).
+says how; `none` leaves `feis_brand_id` null, the unjoined ones). An occurrence whose series one
+filed brand answers is given its `feis_instance_id` when it is ANNOUNCED, before any capture of it
+is held (`series_basis` `announced` on every later release), and its captures land on that
+instance when they arrive, so a field's `feis_instance_id` is the id its results will carry.
 
 A FIELD is one competition a competitor list names, `<feis_id>/<code>`, the same id on every cut. A later capture of the host is a new `version`
 (a capture id; `versions` lists them), never a new field. `state` says how it stands on the cut:
@@ -747,6 +753,33 @@ the corpus `entrants/` part: its rows are schools' counts (`level_counts`), with
 host with a registrant list publishes no such field. An unknown field or version answers no rows and says
 why. On a release without the tables each call refuses by name.
 
+## The feis calendar
+
+```ts
+const g = await rel.calendar.get("plf.2026");  // an instance, an event-year (`<event><year>`), a retired
+                                                // id, a capture (`fweb:PLF26`) or an occurrence id
+g.via;       // "instance" | "formerly" | "feis_id" | "occurrence_id" | null
+g.entries;   // [{ feis_instance_id, feis_brand_id, tier, name_printed, date_lo, date_hi, date_source,
+             //    occurrence_ids, feis_ids, stages: { announced, syllabus, entrants, run, results },
+             //    terminal, carried, formerly }]
+const l = await rel.calendar.list({ stage: "entrants", state: "observed", from: "2026-11-01" });
+             // brand, tier, from, to, stage, state, terminal ("none": still ahead)
+```
+
+ONE ROW PER FEIS INSTANCE, on the id its results carry: a feis-series instance (`<brand>.<year>`),
+announced, held or both, or a rated majors event-year. Each stage (`announced`, `syllabus`,
+`entrants`, `run`, `results`) is `{ state, date, cite }`: `observed` (a capture showed it, `date`
+the day it was first observed, null where no capture dates it, `cite` the capture), `pending` (the
+release holds captures of that kind for the instance's platform, so a later one may show it) or
+`not-captured` (it holds none). A day first observed never moves later from one release to the
+next: a stage an earlier release observed keeps its day, named in `carried` (`["row"]` for a row
+the cut no longer names, kept whole), and a retired id is listed in `formerly`. `terminal` is
+`results`, `withdrawn` (every field withdrawn), `passed-no-results` (its first day is before the
+cut's day), or null for a feis still ahead. Stage dates follow capture timing, not the feis's own
+order: only results after the run is a belief. `get` tries the instance id, then `formerly`, then
+a capture, then an occurrence id, and says which met (`via`). On a release without the table each
+call refuses by name.
+
 ## Teachers and adjudicators
 
 ```ts
@@ -922,6 +955,9 @@ is passed to the dancer resolver as asked (`rel.dancers`, above).
     idq upcoming [--release <spec>] [--state <s,...>] [--feis <id>] [--from <date>] [--to <date>]
     idq upcoming --entrants <field_id> [--version <capture id>]
     idq upcoming --feises [--state upcoming|no-results] [--brand <series>] [--from <date>] [--to <date>]
+    idq calendar [--release <spec>] <instance|feis id|occurrence id>
+    idq calendar [--brand <series>] [--tier <t>] [--from <date>] [--to <date>] [--stage <s>] [--state <s>]
+                 [--terminal results|withdrawn|passed-no-results|none]
     idq teacher [--release <spec>] <name|TD number>
     idq adjudicator [--release <spec>] <name|TD number>
     idq comp [--release <spec>] <feis> <code> [--year y] [--title t]

package/dist/chunks/{index-dy6yvpgk.js → index-cwhyrcyx.js}

@@ -682,6 +682,46 @@ var FEATURES2 = [
     since: 291,
     calls: "upcoming.fields (285 and 290 carry the table empty)"
   },
+  {
+    feature: "upcoming.fields.instance",
+    needs: ["results:upcoming_fields.feis_instance_id"],
+    since: 320,
+    calls: "upcoming.fields' `feis_instance_id` (absent, never null, without it)"
+  },
+  {
+    feature: "calendar",
+    needs: [
+      "feis_instance_id",
+      "feis_brand_id",
+      "tier",
+      "name_printed",
+      "date_lo",
+      "date_hi",
+      "date_source",
+      "occurrence_ids",
+      "feis_ids",
+      "announced_state",
+      "announced_date",
+      "announced_cite",
+      "syllabus_state",
+      "syllabus_date",
+      "syllabus_cite",
+      "entrants_state",
+      "entrants_date",
+      "entrants_cite",
+      "run_state",
+      "run_date",
+      "run_cite",
+      "results_state",
+      "results_date",
+      "results_cite",
+      "terminal",
+      "carried",
+      "formerly"
+    ].map((c) => `results:feis_calendar.${c}`),
+    since: 320,
+    calls: "calendar.get, calendar.list"
+  },
   {
     feature: "upcoming.entrants",
     needs: [
@@ -3819,6 +3859,118 @@ import {
 } from "fs";
 import { join as join3 } from "path";
 
+var CALENDAR_STAGES2 = [
+  "announced",
+  "syllabus",
+  "entrants",
+  "run",
+  "results"
+];
+var CALENDAR_STAGE_STATES2 = [
+  "observed",
+  "pending",
+  "not-captured"
+];
+var CALENDAR_TERMINALS2 = [
+  "results",
+  "withdrawn",
+  "passed-no-results"
+];
+var json = (s, empty) => typeof s === "string" && s !== "" ? JSON.parse(s) : empty;
+function entryOf2(r) {
+  const stages = Object.fromEntries(CALENDAR_STAGES2.map((s) => [
+    s,
+    {
+      state: r[`${s}_state`],
+      date: r[`${s}_date`] ?? null,
+      cite: r[`${s}_cite`] ?? null
+    }
+  ]));
+  return {
+    feis_instance_id: r.feis_instance_id,
+    feis_brand_id: r.feis_brand_id ?? null,
+    tier: r.tier,
+    name_printed: r.name_printed ?? null,
+    date_lo: r.date_lo ?? null,
+    date_hi: r.date_hi ?? null,
+    date_source: r.date_source ?? null,
+    occurrence_ids: json(r.occurrence_ids, []),
+    feis_ids: json(r.feis_ids, []),
+    stages,
+    terminal: r.terminal ?? null,
+    carried: json(r.carried, []),
+    formerly: json(r.formerly, [])
+  };
+}
+var holds = (col) => `EXISTS (SELECT 1 FROM json_each(${col}) WHERE value = ?)`;
+
+class CalendarFinder2 {
+  rel;
+  constructor(rel) {
+    this.rel = rel;
+  }
+  async db() {
+    await this.rel.fetch("results");
+    await this.rel.require("calendar");
+    return this.rel.db("results");
+  }
+  async get(id) {
+    const db = await this.db();
+    const ways = [
+      ["instance", "feis_instance_id = ?"],
+      ["formerly", holds("formerly")],
+      ["feis_id", holds("feis_ids")],
+      ["occurrence_id", holds("occurrence_ids")]
+    ];
+    for (const [via, where] of ways) {
+      const rows = db.query(`SELECT * FROM feis_calendar WHERE ${where} ORDER BY feis_instance_id`).all(id);
+      if (rows.length > 0)
+        return { tag: this.rel.tag, asked: id, via, entries: rows.map(entryOf2) };
+    }
+    return {
+      tag: this.rel.tag,
+      asked: id,
+      via: null,
+      entries: [],
+      why: `the calendar names no instance, capture or occurrence "${id}"`
+    };
+  }
+  async list(q = {}) {
+    if (q.stage !== undefined && !CALENDAR_STAGES2.includes(q.stage))
+      throw new Error(`calendar.list: no stage "${q.stage}" (the stages are ${CALENDAR_STAGES2.join(", ")})`);
+    if (q.state !== undefined && !CALENDAR_STAGE_STATES2.includes(q.state))
+      throw new Error(`calendar.list: no state "${q.state}" (the states are ${CALENDAR_STAGE_STATES2.join(", ")})`);
+    if (q.terminal !== undefined && q.terminal !== "none" && !CALENDAR_TERMINALS2.includes(q.terminal))
+      throw new Error(`calendar.list: no terminal "${q.terminal}" (the terminals are ${CALENDAR_TERMINALS2.join(", ")}, none)`);
+    const db = await this.db();
+    const where = [];
+    const args = [];
+    const add = (sql, ...v) => {
+      where.push(sql);
+      args.push(...v);
+    };
+    if (q.brand !== undefined)
+      add("feis_brand_id = ?", q.brand);
+    if (q.tier !== undefined)
+      add("tier = ?", q.tier);
+    if (q.from !== undefined)
+      add("date_lo >= ?", q.from);
+    if (q.to !== undefined)
+      add("date_lo <= ?", q.to);
+    if (q.stage !== undefined)
+      add(`${q.stage}_state = ?`, q.state ?? "observed");
+    else if (q.state !== undefined)
+      add(`(${CALENDAR_STAGES2.map((s) => `${s}_state = ?`).join(" OR ")})`, ...CALENDAR_STAGES2.map(() => q.state));
+    if (q.terminal === "none")
+      add("terminal IS NULL");
+    else if (q.terminal !== undefined)
+      add("terminal = ?", q.terminal);
+    const sql = `SELECT * FROM feis_calendar${where.length > 0 ? ` WHERE ${where.join(" AND ")}` : ""} ORDER BY date_lo IS NULL, date_lo, feis_instance_id`;
+    const rows = db.query(sql).all(...args);
+    return { tag: this.rel.tag, entries: rows.map(entryOf2) };
+  }
+}
+
 import { Age as Age3 } from "@finbheara/domain/age";
 import { compTitle as compTitle3 } from "@finbheara/domain/title";
 function youngest2(answers) {
@@ -4119,7 +4271,7 @@ var FIELD_STATES2 = [
   "withdrawn"
 ];
 var DEPARTURE_REASONS2 = FIELD_STATES2.filter((s) => s !== "pending");
-var json = (s, empty) => typeof s === "string" && s !== "" ? JSON.parse(s) : empty;
+var json2 = (s, empty) => typeof s === "string" && s !== "" ? JSON.parse(s) : empty;
 function fieldOf(r) {
   const countOnly = r.count_only === 1;
   return {
@@ -4135,6 +4287,7 @@ function fieldOf(r) {
     date_hi: r.date_hi ?? null,
     year: r.year,
     feis_brand_id: r.feis_brand_id ?? null,
+    ...r.feis_instance_id === undefined ? {} : { feis_instance_id: r.feis_instance_id ?? null },
     comp: r.comp_arm === null ? null : {
       arm: r.comp_arm,
       source: r.comp_source ?? null,
@@ -4147,19 +4300,19 @@ function fieldOf(r) {
       why: r.comp_why ?? null
     },
     state: r.state,
-    flags: json(r.flags, []),
-    results_competitions: json(r.results_competitions, []),
-    results_feis_ids: json(r.results_feis_ids, []),
-    held_out: json(r.held_out, []),
+    flags: json2(r.flags, []),
+    results_competitions: json2(r.results_competitions, []),
+    results_feis_ids: json2(r.results_feis_ids, []),
+    held_out: json2(r.held_out, []),
     merged_into: r.merged_into ?? null,
     version: r.version,
-    versions: json(r.versions, []),
+    versions: json2(r.versions, []),
     captured_date: r.captured_date,
     sha256: r.sha256,
-    limits: json(r.limits, []),
+    limits: json2(r.limits, []),
     entrants: r.entrants,
     stated_rows: r.stated_rows ?? null,
-    printed_total: json(r.printed_total, null)
+    printed_total: json2(r.printed_total, null)
   };
 }
 function entrantOf(r) {
@@ -4176,30 +4329,30 @@ function entrantOf(r) {
     school_printed: r.school_printed ?? null,
     school_id: r.school_id ?? null,
     school_rung: r.school_rung,
-    school_candidates: json(r.school_candidates, []),
-    competitions: json(r.competitions, []),
-    field_ids: json(r.field_ids, []),
-    level_counts: json(r.level_counts, null),
+    school_candidates: json2(r.school_candidates, []),
+    competitions: json2(r.competitions, []),
+    field_ids: json2(r.field_ids, []),
+    level_counts: json2(r.level_counts, null),
     yob: r.yob ?? null,
-    asked: json(r.asked, null),
+    asked: json2(r.asked, null),
     arm: r.arm ?? null,
-    candidates: json(r.candidates, []),
-    flags: json(r.flags, [])
+    candidates: json2(r.candidates, []),
+    flags: json2(r.flags, [])
   };
 }
 function feisOf(r) {
   return {
     occurrence_id: r.occurrence_id,
-    occurrence_ids: json(r.occurrence_ids, []),
+    occurrence_ids: json2(r.occurrence_ids, []),
     name_printed: r.name_printed,
     date_lo: r.date_lo,
     date_hi: r.date_hi ?? null,
     year: r.year,
-    hosts: json(r.hosts, []),
+    hosts: json2(r.hosts, []),
     feis_brand_id: r.feis_brand_id ?? null,
     feis_instance_id: r.feis_instance_id ?? null,
     series_basis: r.series_basis,
-    brand_candidates: json(r.brand_candidates, []),
+    brand_candidates: json2(r.brand_candidates, []),
     captured_id: r.captured_id,
     state: r.results_state
   };
@@ -4389,6 +4542,7 @@ class Release2 {
   teams;
   events;
   upcoming;
+  calendar;
   tabs;
   panels;
   feisPanels;
@@ -4415,6 +4569,7 @@ class Release2 {
     this.teams = new TeamFinder2(this);
     this.events = new EventFinder2(this);
     this.upcoming = new UpcomingFinder2(this);
+    this.calendar = new CalendarFinder2(this);
     this.tabs = new TabFinder2(this);
     this.panels = new PanelFinder2(this);
     this.feisPanels = new FeisPanelFinder2(this);
@@ -5138,4 +5293,4 @@ function staleWarning2(answered, latest, floor, tags = [], command = "idq") {
   return `answered from ${answered}. ${floorTag ?? `cut ${floor.cut}`} is required${why}: run \`${command} use ${floor.cut}\` to get it`;
 }
 
-export { DATABASES2, planAsset2, sha256File2, unzstdTo2, NAME_LEVELS2, nameLevel2, TabFinder2, PanelFinder2, FeisPanelFinder2, columnsOf2, FEATURES2, capabilityOf2, needsRelease2, rosterOf2, NO_CALENDAR2, NO_UPCOMING2, FeisFinder2, ADVANCEMENT_DANCES2, entryRank2, FEIS_LOCAL_ID_FLOOR2, ResultFinder2, MajorsFinder2, LINEAGE_FILE2, linksOfLineage2, releaseSchoolGraph2, readsSpanishNames2, SchoolResolver2, initialsOnly2, nameOrderOf, DancerResolver2, readPopulation2, syllabusSourceOf2, canonicalOf2, CompResolver2, StaffFinder2, TeamFinder2, EventFinder2, defaultBuilders2, indexPath2, indexKey2, isCurrent2, buildIndex2, ensureIndex2, listIndexes2, readPin2, youngest2, dancerResolverOf2, RegistrationResolver2, ghRemote2, httpsRemote2, fallbackRemote2, setRemote2, defaultRemote, FIELD_STATES2, DEPARTURE_REASONS2, UpcomingFinder2, resolveTag2, Release2, openRelease2, openCached2, DEFAULT_KEEP2, ReleaseManager2, releases2, LOCAL_DIR2, localRoot2, newerThan2, incomplete2, releaseVersion2, pickBuild2, buildTag2, lacks, openBuild2, sweepBuilds2, LATEST_CHECK_MS2, LATEST_CHECK_BUDGET_MS2, latestCheckPath2, readLatestCheck2, latestCheck2, within, staleWarning2 };
+export { DATABASES2, planAsset2, sha256File2, unzstdTo2, NAME_LEVELS2, nameLevel2, TabFinder2, PanelFinder2, FeisPanelFinder2, columnsOf2, FEATURES2, capabilityOf2, needsRelease2, rosterOf2, NO_CALENDAR2, NO_UPCOMING2, FeisFinder2, ADVANCEMENT_DANCES2, entryRank2, FEIS_LOCAL_ID_FLOOR2, ResultFinder2, MajorsFinder2, LINEAGE_FILE2, linksOfLineage2, releaseSchoolGraph2, readsSpanishNames2, SchoolResolver2, initialsOnly2, nameOrderOf, DancerResolver2, readPopulation2, syllabusSourceOf2, canonicalOf2, CompResolver2, StaffFinder2, TeamFinder2, EventFinder2, defaultBuilders2, indexPath2, indexKey2, isCurrent2, buildIndex2, ensureIndex2, listIndexes2, readPin2, CALENDAR_STAGES2, CALENDAR_STAGE_STATES2, CALENDAR_TERMINALS2, CalendarFinder2, youngest2, dancerResolverOf2, RegistrationResolver2, ghRemote2, httpsRemote2, fallbackRemote2, setRemote2, defaultRemote, FIELD_STATES2, DEPARTURE_REASONS2, UpcomingFinder2, resolveTag2, Release2, openRelease2, openCached2, DEFAULT_KEEP2, ReleaseManager2, releases2, LOCAL_DIR2, localRoot2, newerThan2, incomplete2, releaseVersion2, pickBuild2, buildTag2, lacks, openBuild2, sweepBuilds2, LATEST_CHECK_MS2, LATEST_CHECK_BUDGET_MS2, latestCheckPath2, readLatestCheck2, latestCheck2, within, staleWarning2 };

package/dist/cli.js

@@ -21,7 +21,7 @@ import {
   latestCheck2,
   within,
   staleWarning2
-} from "./chunks/index-dy6yvpgk.js";
+} from "./chunks/index-cwhyrcyx.js";
 import"./chunks/index-hghdy980.js";
 
 var USAGE_HEADER = "usage: idq <verb> [--cache <dir>] [--repo <owner/name>] [--json] [--live]";
@@ -392,6 +392,21 @@ var VERBS = [
       "                                    held-out competitions)"
     ]
   },
+  {
+    verb: "calendar",
+    value: ["--release", "--brand", "--tier", "--from", "--to", "--stage", "--state", "--terminal"],
+    bool: [],
+    usage: [
+      "  calendar [--release <spec>] <instance|feis id|occurrence id>",
+      "                                    one feis instance's stages: announced, syllabus, entrants,",
+      "                                    run and results, each observed, pending or not-captured,",
+      "                                    the day first observed and the capture that observed it",
+      "  calendar [--brand <series>] [--tier T1..T4] [--from <date>] [--to <date>]",
+      "           [--stage announced|syllabus|entrants|run|results] [--state observed|pending|not-captured]",
+      "           [--terminal results|withdrawn|passed-no-results|none]",
+      "                                    the instances a query names, by first day"
+    ]
+  },
   {
     verb: "teacher",
     value: ["--release"],
@@ -799,6 +814,7 @@ var ANSWERING = new Set([
   "teams",
   "events",
   "upcoming",
+  "calendar",
   "teacher",
   "adjudicator",
   "comp",
@@ -1533,6 +1549,42 @@ async function main(argv, io = {}) {
           rel.close();
         }
       }
+      case "calendar": {
+        const rel = await open(spec, { ...opts, assets: [] });
+        try {
+          const line = (e) => `  ${e.date_lo ?? "?"}  ${e.feis_instance_id}  ${e.tier}  ${["announced", "syllabus", "entrants", "run", "results"].map((s) => `${s}:${e.stages[s].state === "observed" ? e.stages[s].date ?? "seen" : e.stages[s].state}`).join(" ")}  [${e.terminal ?? "ahead"}]${e.name_printed !== null ? `  "${e.name_printed}"` : ""}`;
+          if (rest.length > 0) {
+            const a = await rel.calendar.get(rest.join(" "));
+            out(a, () => {
+              for (const e of a.entries) {
+                say(line(e));
+                for (const s of ["announced", "syllabus", "entrants", "run", "results"])
+                  say(`      ${s}  ${e.stages[s].state}  ${e.stages[s].date ?? "-"}  ${e.stages[s].cite ?? "-"}${e.carried.includes(s) ? "  (carried)" : ""}`);
+              }
+              say(`${a.entries.length} instance(s) for "${a.asked}"${a.via !== null ? ` by ${a.via}` : ""}${a.why !== undefined ? ` (${a.why})` : ""} in ${a.tag}`);
+            });
+            return a.entries.length === 0 ? 1 : 0;
+          }
+          const v = (f) => p.flags.get(f);
+          const a = await rel.calendar.list({
+            ...v("--brand") !== undefined ? { brand: v("--brand") } : {},
+            ...v("--tier") !== undefined ? { tier: v("--tier") } : {},
+            ...v("--from") !== undefined ? { from: v("--from") } : {},
+            ...v("--to") !== undefined ? { to: v("--to") } : {},
+            ...v("--stage") !== undefined ? { stage: v("--stage") } : {},
+            ...v("--state") !== undefined ? { state: v("--state") } : {},
+            ...v("--terminal") !== undefined ? { terminal: v("--terminal") } : {}
+          });
+          out(a, () => {
+            for (const e of a.entries)
+              say(line(e));
+            say(`${a.entries.length} instance(s) in ${a.tag}`);
+          });
+          return a.entries.length === 0 ? 1 : 0;
+        } finally {
+          rel.close();
+        }
+      }
       case "teacher":
       case "adjudicator": {
         if (rest.length === 0) {

package/dist/index.js

@@ -44,6 +44,10 @@ import {
   ensureIndex2,
   listIndexes2,
   readPin2,
+  CALENDAR_STAGES2,
+  CALENDAR_STAGE_STATES2,
+  CALENDAR_TERMINALS2,
+  CalendarFinder2,
   youngest2,
   dancerResolverOf2,
   RegistrationResolver2,
@@ -76,7 +80,7 @@ import {
   readLatestCheck2,
   latestCheck2,
   staleWarning2
-} from "./chunks/index-dy6yvpgk.js";
+} from "./chunks/index-cwhyrcyx.js";
 import {
   cacheRoot2,
   repoOf2
@@ -93,6 +97,10 @@ import {
 export {
   ADVANCEMENT_DANCES2 as ADVANCEMENT_DANCES,
   ARCHIVE_TAG2 as ARCHIVE_TAG,
+  CALENDAR_STAGES2 as CALENDAR_STAGES,
+  CALENDAR_STAGE_STATES2 as CALENDAR_STAGE_STATES,
+  CALENDAR_TERMINALS2 as CALENDAR_TERMINALS,
+  CalendarFinder2 as CalendarFinder,
   CompResolver2 as CompResolver,
   DATABASES2 as DATABASES,
   DEFAULT_KEEP2 as DEFAULT_KEEP,

package/dist/types/calendar.d.ts

@@ -0,0 +1,54 @@
+import type { Release } from "./release.js";
+export type CalendarStage = "announced" | "syllabus" | "entrants" | "run" | "results";
+export declare const CALENDAR_STAGES: readonly CalendarStage[];
+export type CalendarStageState = "observed" | "pending" | "not-captured";
+export declare const CALENDAR_STAGE_STATES: readonly CalendarStageState[];
+export type CalendarTerminal = "results" | "withdrawn" | "passed-no-results";
+export declare const CALENDAR_TERMINALS: readonly CalendarTerminal[];
+export interface CalendarStageValue {
+    state: CalendarStageState;
+    date: string | null;
+    cite: string | null;
+}
+export interface CalendarEntry {
+    feis_instance_id: string;
+    feis_brand_id: string | null;
+    tier: string;
+    name_printed: string | null;
+    date_lo: string | null;
+    date_hi: string | null;
+    date_source: "run" | "announced" | null;
+    occurrence_ids: string[];
+    feis_ids: string[];
+    stages: Record<CalendarStage, CalendarStageValue>;
+    terminal: CalendarTerminal | null;
+    carried: string[];
+    formerly: string[];
+}
+export interface CalendarQuery {
+    brand?: string;
+    tier?: string;
+    from?: string;
+    to?: string;
+    stage?: CalendarStage;
+    state?: CalendarStageState;
+    terminal?: CalendarTerminal | "none";
+}
+export interface CalendarAnswer {
+    tag: string;
+    entries: CalendarEntry[];
+}
+export interface CalendarGetAnswer {
+    tag: string;
+    asked: string;
+    via: "instance" | "formerly" | "feis_id" | "occurrence_id" | null;
+    entries: CalendarEntry[];
+    why?: string;
+}
+export declare class CalendarFinder {
+    private readonly rel;
+    constructor(rel: Release);
+    private db;
+    get(id: string): Promise<CalendarGetAnswer>;
+    list(q?: CalendarQuery): Promise<CalendarAnswer>;
+}

package/dist/types/index.d.ts

@@ -26,4 +26,5 @@ export { type EntryRow, type StreamCompetition, type StreamQuery, type StreamRow
 export { type FeisPanelSeat, FeisPanelFinder, PanelFinder, type PanelSeat, type RegisterRow, type TabAnswer, TabFinder, type TabQuery, type TabRow, type TabStreamQuery, } from "./tabs.js";
 export { EventFinder, type EventYear, type EventYearQuery, type ResultRoster, type RosterMember, type RosterTeam, TeamFinder, type TeamResult, } from "./teams.js";
 export { type EntrantCandidate, FIELD_STATES, type FieldComp, DEPARTURE_REASONS, type DepartureReason, type FieldState, type HeldOut, type UpcomingDeparture, type UpcomingDepartureAnswer, type UpcomingDepartureQuery, type UpcomingEntrant, type UpcomingEntrantAnswer, type UpcomingEntrantQuery, type UpcomingFeis, type UpcomingFeisAnswer, type UpcomingFeisQuery, type UpcomingFeisState, type UpcomingField, type UpcomingFieldAnswer, type UpcomingFieldQuery, UpcomingFinder, type UpcomingHost, } from "./upcoming.js";
+export { CALENDAR_STAGES, CALENDAR_STAGE_STATES, CALENDAR_TERMINALS, type CalendarAnswer, type CalendarEntry, CalendarFinder, type CalendarGetAnswer, type CalendarQuery, type CalendarStage, type CalendarStageState, type CalendarStageValue, type CalendarTerminal, } from "./calendar.js";
 export { ARCHIVE_TAG, type ArchiveTag, type ReleaseSpec, compareTagsNewestFirst, cutOf, parseArchiveTag, parseReleaseSpec, pickTag, renderArchiveTag, } from "./tag.js";

package/dist/types/release.d.ts

@@ -1,5 +1,6 @@
 import { Database } from "bun:sqlite";
 import { type AssetPlan, type LandedFile, type Receipt, type ReleaseManifest } from "./assets.js";
+import { CalendarFinder } from "./calendar.js";
 import { CompResolver } from "./comps.js";
 import { type ClientOptions } from "./config.js";
 import { DancerResolver } from "./dancers.js";
@@ -47,6 +48,7 @@ export declare class Release {
     readonly teams: TeamFinder;
     readonly events: EventFinder;
     readonly upcoming: UpcomingFinder;
+    readonly calendar: CalendarFinder;
     readonly tabs: TabFinder;
     readonly panels: PanelFinder;
     readonly feisPanels: FeisPanelFinder;

package/dist/types/upcoming.d.ts

@@ -57,6 +57,7 @@ export interface UpcomingField {
     date_hi: string | null;
     year: number;
     feis_brand_id: string | null;
+    feis_instance_id?: string | null;
     comp: FieldComp | null;
     state: FieldState;
     flags: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@finbheara/archive-client",
-	"version": "0.32.0",
+	"version": "0.34.0",
 	"description": "Open a versioned release of an Irish dance results archive: download, verify, decompress and cache it by tag, keep the cache, and resolve feises and schools against it",
 	"keywords": ["irish-dance", "results", "release", "cache", "sqlite"],
 	"license": "MIT",