@ai-matrx/records 0.28.0 → 0.30.0

package/dist/use-cases/index.d.ts

@@ -0,0 +1,447 @@
+import { T as TableType, a as TableDisplay, S as StorageMode, F as FieldTypeWord, b as FieldSource, C as ComputeOn, c as FieldRule, d as FieldSensitivity, e as ContextPolicy, R as RelationFlavor, f as RelationCardinality, O as OnDelete } from '../field-D08d_e7R.js';
+
+/**
+ * Who the data belongs to. A test organization is created under this name — the
+ * owner's law #4: every organization, table, record, form, portal, dashboard,
+ * document, checklist, booking page, capture sheet, subscription, pipeline and
+ * enrichment created for a test carries the use case's own name. Cleanup finds
+ * a test organization by `cleanupTag` in its settings, NEVER by a junk name.
+ */
+interface BusinessIdentity {
+    /** "Harbor Dental Group" — what goes on the organization, the invoice, the screenshot. */
+    name: string;
+    /** "Harbor Dental Group, PLLC" — used on documents that need the legal entity. */
+    legalName?: string;
+    /** One line a stranger would understand: "A six-chair family dental practice." */
+    describes: string;
+    /** Plausible and synthesized. Never a real business's real address. */
+    address: PostalAddress;
+    /** Synthesized, E.164-shaped or the local convention the document uses. */
+    phone: string;
+    /**
+     * Synthesized. NOT a `.example` domain — those read as fake on a screenshot.
+     * Optional, because the law welcomes personal-life use cases and a household
+     * renovation or a family recipe collection genuinely has no website.
+     */
+    website?: string;
+    /** Synthesized mailbox on the same domain: "frontdesk@harbordentalgroup.com". */
+    email: string;
+    /** IANA zone, so dates in the rows make sense together. */
+    timezone: string;
+}
+interface PostalAddress {
+    line1: string;
+    line2?: string;
+    city: string;
+    /** State, province or region, in the country's own convention. */
+    region: string;
+    postalCode: string;
+    /** ISO 3166-1 alpha-2. */
+    country: string;
+}
+/**
+ * One table of the business, in the words the practitioner uses. `token` is the
+ * slug the store addresses it by; `name` is what a person reads.
+ */
+interface UseCaseTable {
+    /** snake_case, singular, the practitioner's noun: "patient", "work_order". */
+    token: string;
+    /** "Patients", "Work orders". */
+    name: string;
+    labelSingular: string;
+    labelPlural: string;
+    /** REC-32. One of the seven, closed. Most business tables are `entity`. */
+    type: TableType;
+    display: TableDisplay;
+    /** REC-4. `light` is the whole document; `heavy` is indexed on write. */
+    weight: StorageMode;
+    ordered: boolean;
+    /** A lucide icon name, so the screen is not a wall of identical rows. */
+    icon?: string;
+    /** REC-2. The field key whose value titles a record. Must be a declared field. */
+    titleField: string;
+    /** What this table is FOR, in the practitioner's words. */
+    describes: string;
+    fields: UseCaseField[];
+    /** The seed rows. Enough that the screen looks like a working business. */
+    rows: UseCaseRow[];
+}
+/**
+ * One field. `parityType` is the word a person picks in the UI and it must be
+ * one the store resolves — one of the thirteen parity types, one of the five
+ * behaviours, or one of the plain synonyms (see `FieldTypeWord`).
+ */
+interface UseCaseField {
+    /** snake_case, the practitioner's own name for it: "date_of_birth", "po_number". */
+    key: string;
+    /** "Date of birth", "PO number". Sentence case, the way the form reads. */
+    label: string;
+    parityType: FieldTypeWord;
+    /** FLD-2. The shape of the value, never a second behaviour. */
+    multi?: boolean;
+    /** FLD-2. The values carry their own dates. */
+    dated?: boolean;
+    required?: boolean;
+    /** FLD-N-1. The unit CHANGES THE MEANING and lives on the field: "USD", "lb", "mi". */
+    unit?: string | null;
+    /** "currency", "percent", "email", "phone", "url", "date". Never decoration. */
+    format?: string | null;
+    /** FLD-7. Where the values come from. Defaults to `manual`. */
+    source?: FieldSource;
+    /** FLD-9. A formula says whether it computes on read or on write. */
+    computeOn?: ComputeOn;
+    /** FLD-3. Validation rules the store will enforce. */
+    rules?: FieldRule[];
+    /**
+     * For `select` / `multi_select`: the REAL lifecycle words of this business,
+     * in the order they actually happen. "Scheduled, Confirmed, Seen, No-show" —
+     * never "Option A, Option B".
+     */
+    choices?: string[];
+    /** For a relation field: the `token` of the table it points at. */
+    relationTarget?: string;
+    relationMax?: number;
+    /** AGT-7. The ceiling a merge field's delivery can never widen. */
+    sensitivity: FieldSensitivity;
+    /** FLD-12. Whether an agent may see this field's values at all. */
+    contextPolicy: ContextPolicy;
+    /** What the practitioner would be told about this field, if anything. */
+    help?: string;
+}
+/**
+ * One row of seed data.
+ *
+ * `key` is a stable LOCAL id (not a UUID): relationships across tables point at
+ * it, so a template is readable and a seeder can resolve the graph in one pass
+ * without inventing identifiers. Use a meaningful slug — "patient-rivera-m",
+ * not "row-7".
+ */
+interface UseCaseRow {
+    key: string;
+    /**
+     * Keyed by the table's field keys. A relation field's value is the `key` (or
+     * an array of keys) of rows in the target table.
+     */
+    values: Record<string, unknown>;
+}
+/**
+ * REL-1…REL-9. The domain truth, stated once: "an invoice belongs to the job it
+ * bills, and a job belongs to the client who asked for it."
+ *
+ * The field side carries `relationTarget`; this is the declaration a seeder
+ * reads, because it also carries the flavour, the cardinality, what happens to
+ * the far side on delete, and the reverse name.
+ */
+interface UseCaseRelationship {
+    /** One sentence of domain truth. Not "links A to B". */
+    describes: string;
+    /** The table that HOLDS the relation field. */
+    fromTable: string;
+    /** The field key on `fromTable`. Must be declared and must be a relation. */
+    fromField: string;
+    /** The `token` of the table it points at. */
+    toTable: string;
+    /** REL-1. Ownership is one fact, stored once, read from the field's side. */
+    flavor: RelationFlavor;
+    /** REL-7. */
+    cardinality: RelationCardinality;
+    /** REL-2. What happens to the far side, separate from flavour. */
+    onDelete: OnDelete;
+    /** REL-9. The reverse, visible from both ends, and NOT a second field. */
+    inverseKey: string;
+}
+/** Who is allowed to open a form. */
+type FormAudience = "public" | "member" | "staff";
+/**
+ * A form a practitioner in this business would actually put in front of someone
+ * — "the Harbor Dental new-patient intake", never "Test Form 1".
+ */
+interface UseCaseForm {
+    token: string;
+    name: string;
+    /** What it is for, and who fills it in. */
+    describes: string;
+    audience: FormAudience;
+    /** The table a submission becomes a record of. */
+    table: string;
+    fields: UseCaseFormField[];
+    submitLabel: string;
+    /** What the person sees after they submit. Real words, not "Success!". */
+    confirmation: string;
+}
+interface UseCaseFormField {
+    /** A field key on the form's table. */
+    fieldKey: string;
+    /** Override the field's own label when the form asks it differently. */
+    label?: string;
+    required?: boolean;
+    /** The helper line under the input, if a practitioner would want one. */
+    help?: string;
+}
+/**
+ * The real lifecycle a record moves through in this business, in order. A
+ * pipeline's stages are the words the staff say out loud.
+ */
+interface UseCasePipeline {
+    token: string;
+    name: string;
+    describes: string;
+    /** The table whose records move through it. */
+    table: string;
+    /** The `select` field that holds the current stage. */
+    stageField: string;
+    stages: UseCasePipelineStage[];
+}
+interface UseCasePipelineStage {
+    /** Must appear in the stage field's `choices`. */
+    key: string;
+    label: string;
+    /** What is true of a record sitting here, and what moves it on. */
+    describes: string;
+    /** Roughly how long a record sits here, so a board looks believable. */
+    typicalDurationDays?: number;
+}
+/**
+ * The question the owner of this business actually asks a dashboard on Monday
+ * morning — "how much have we invoiced this month that hasn't been paid?" —
+ * plus how it is answered from the tables above.
+ */
+interface UseCaseDashboardQuestion {
+    /** The question in the practitioner's own words, ending in a question mark. */
+    question: string;
+    /** Why they care. What they DO differently depending on the answer. */
+    whyItMatters: string;
+    table: string;
+    aggregate: "count" | "sum" | "avg" | "min" | "max";
+    /** The field aggregated. Omitted only for `count`. */
+    of?: string;
+    groupBy?: string;
+    /** A plain-language filter: "status is Unpaid and due_date is before today". */
+    filter?: string;
+    /** What the number IS: "USD", "days", "appointments". */
+    answerUnit: string;
+}
+/**
+ * A document this business really sends. The body carries merge fields in
+ * `{{double_brace}}` form; every one of them is declared below and resolves to a
+ * field on the document's table (or a stated literal).
+ */
+interface UseCaseDocumentTemplate {
+    token: string;
+    name: string;
+    describes: string;
+    table: string;
+    /** The subject or title line, merge fields allowed. */
+    title: string;
+    /** The body. Real prose this business would send, merge fields inline. */
+    body: string;
+    mergeFields: UseCaseMergeField[];
+}
+interface UseCaseMergeField {
+    /** The token inside `{{ }}` in the body. */
+    key: string;
+    /**
+     * The field key it reads, on the document's table — or, when it is not a
+     * field, the word `business` (from `BusinessIdentity`) or `today`.
+     */
+    from: string;
+    describes: string;
+}
+/** How a notification reaches someone. */
+type NotificationChannel = "email" | "sms" | "in_app";
+/**
+ * The one automatic message this business would genuinely want — the thing a
+ * practitioner sets up on day one and never turns off.
+ */
+interface UseCaseNotificationRule {
+    token: string;
+    name: string;
+    describes: string;
+    when: UseCaseNotificationTrigger;
+    /** Who it goes to, in the business's own words: "the assigned hygienist". */
+    audience: string;
+    channel: NotificationChannel;
+    /** The actual message. Merge fields allowed, same convention as documents. */
+    message: string;
+}
+interface UseCaseNotificationTrigger {
+    table: string;
+    event: "created" | "updated" | "stage_entered" | "due" | "overdue";
+    /** For `stage_entered`: the stage key. */
+    stage?: string;
+    /** For `due` / `overdue`: the date field watched. */
+    field?: string;
+    /** For `due`: how many days ahead it fires. */
+    daysBefore?: number;
+}
+/**
+ * Where the shape and the values came from. `synthesized` means a person wrote
+ * plausible values out of domain knowledge; `public-data` means the numbers or
+ * names were derived from a genuinely public dataset, which is named.
+ *
+ * Either way the law holds: no real person, no real customer, no production row.
+ */
+interface UseCaseProvenance {
+    kind: "synthesized" | "public-data";
+    /** Named when `kind` is `public-data`. */
+    source?: string;
+    /** Who or what wrote this file, and when. */
+    authoredBy: string;
+    authoredOn: string;
+    /**
+     * The affirmation, carried in the data so a reviewer can see it: every person,
+     * address, phone and mailbox here is invented and belongs to nobody.
+     */
+    noRealPeople: true;
+}
+/** One real business, and everything a test, seed, demo or screenshot needs of it. */
+interface UseCase {
+    /** kebab-case and unique: "harbor-dental-new-patient-intake". */
+    id: string;
+    /**
+     * THE SENTENCE. Who the user is, what business they run, and what job this
+     * exact feature does for them — one sentence, at the top, before anything
+     * else. This is the first thing the law asks for and the validator checks it.
+     */
+    useCase: string;
+    /** The industry, for rotation: "Dentistry", "Property management". */
+    industry: string;
+    business: BusinessIdentity;
+    /**
+     * The tag written into a test organization's settings so cleanup can find it.
+     * Cleanup finds test data by THIS, never by a junk name.
+     */
+    cleanupTag: string;
+    tables: UseCaseTable[];
+    relationships: UseCaseRelationship[];
+    form: UseCaseForm;
+    pipeline: UseCasePipeline;
+    dashboardQuestion: UseCaseDashboardQuestion;
+    documentTemplate: UseCaseDocumentTemplate;
+    notificationRule: UseCaseNotificationRule;
+    provenance: UseCaseProvenance;
+}
+/** What the registry lists without loading a use case's rows. */
+interface UseCaseSummary {
+    id: string;
+    useCase: string;
+    industry: string;
+    businessName: string;
+    /** How many tables and rows the file carries, so a caller can pick by size. */
+    tableCount: number;
+    rowCount: number;
+}
+
+/** One banned pattern, with the reason and what to do instead. */
+interface PlaceholderPattern {
+    /** Stable id, used in the guard's output so a failure is greppable. */
+    id: string;
+    /** Matches the junk. Always global + case-insensitive. */
+    test: RegExp;
+    /** What is wrong with it, in one line. */
+    why: string;
+    /** What to write instead. */
+    instead: string;
+    /**
+     * Skip the hit when the LINE it sits on matches this. For words that are junk
+     * in one world and vocabulary in another: "Acme" is a cartoon company, but
+     * ACME is also RFC 8555, the protocol Let's Encrypt speaks, and a guard that
+     * cannot tell them apart will be told to shut up rather than obeyed.
+     */
+    unlessLineMatches?: RegExp;
+}
+/**
+ * The pragma that exempts a single line. The reason is not optional: a bare
+ * `matrx-real-data:allow` does not match and does not exempt anything.
+ */
+declare const ALLOW_PRAGMA: RegExp;
+/**
+ * THE LIST. Every entry is anchored on word boundaries so it catches the token
+ * and not the vocabulary it lives inside.
+ */
+declare const PLACEHOLDER_PATTERNS: readonly PlaceholderPattern[];
+/** One hit of one pattern. */
+interface PlaceholderHit {
+    patternId: string;
+    /** The exact text that matched. */
+    match: string;
+    why: string;
+    instead: string;
+}
+/**
+ * Every banned pattern in `text`, ignoring any LINE carrying the allow pragma.
+ *
+ * Line-scoped rather than whole-text so one exemption never blinds the rest of
+ * a file, which is the failure mode of a file-level ignore comment.
+ */
+declare function findPlaceholders(text: string): PlaceholderHit[];
+/** The sentence a guard or a suite prints for one hit. Never a bare code. */
+declare function describePlaceholder(hit: PlaceholderHit): string;
+
+/** Every word a `parityType` may be: the thirteen, the five behaviours, the synonyms. */
+declare const RESOLVABLE_FIELD_TYPE_WORDS: readonly string[];
+/**
+ * The minimum a seeded business needs before a screen looks like it is working
+ * rather than like a fixture. Below this, a screenshot shows an empty state.
+ *
+ * It was 8 until a real dataset argued with it: a whole-house renovation has SIX
+ * ROOMS, and demanding eight would have meant inventing two rooms that do not
+ * exist — which is the exact failure this whole library is against. Six rooms on
+ * a board is a working project, not an empty screen. So the floor is what a
+ * screen genuinely needs, and the suite keeps the stronger check where it
+ * belongs: at least 20 rows across the whole use case.
+ */
+declare const MIN_ROWS_IN_PRIMARY_TABLE = 5;
+/** A refusal: what is wrong, where, and what to do. */
+interface UseCaseProblem {
+    /** Dotted path into the use case: "tables[1].fields[3].choices". */
+    at: string;
+    /** The sentence. Always says what to do, never only what is wrong. */
+    says: string;
+}
+interface UseCaseVerdict {
+    ok: boolean;
+    problems: UseCaseProblem[];
+}
+/**
+ * Check one use case. Returns every problem rather than the first, because a
+ * crew fixing a dataset wants the whole list in one pass.
+ */
+declare function validateUseCase(useCase: UseCase): UseCaseVerdict;
+/**
+ * Validate, and throw with every problem listed. This is what a seeder calls
+ * before it writes anything to a live organization — a half-valid dataset is
+ * worse than none, because it produces a screen that looks like it worked.
+ */
+declare function assertUseCase(useCase: UseCase): void;
+
+/**
+ * Every registered use case, by id. ADD YOUR LINE HERE and nowhere else.
+ *
+ * Keep it alphabetical — it is read by people looking for an industry.
+ */
+declare const USE_CASE_LOADERS: Record<string, () => Promise<{
+    useCase: UseCase;
+}>>;
+/** The ids, sorted, so any listing is stable. */
+declare function useCaseIds(): string[];
+/** Load one by id. Throws by name when it is not registered. */
+declare function loadUseCase(id: string): Promise<UseCase>;
+/** Load all of them. For the suite, the seeders and the census. */
+declare function loadAllUseCases(): Promise<UseCase[]>;
+/** Summarize one without the caller walking its tables. */
+declare function summarize(useCase: UseCase): UseCaseSummary;
+/** Every use case, summarized. Loads all of them, so call it server-side. */
+declare function listUseCases(): Promise<UseCaseSummary[]>;
+/**
+ * Pick the use case for a given consumer, deterministically.
+ *
+ * The law says to ROTATE across industries so the platform is exercised by many
+ * kinds of business rather than one toy. A suite, a demo or a screenshot script
+ * passes a stable name for itself and always gets the same business — stable
+ * enough to assert on, different enough across consumers that the platform gets
+ * exercised broadly.
+ */
+declare function useCaseFor(consumer: string): string;
+
+export { ALLOW_PRAGMA, type BusinessIdentity, type FormAudience, MIN_ROWS_IN_PRIMARY_TABLE, type NotificationChannel, PLACEHOLDER_PATTERNS, type PlaceholderHit, type PlaceholderPattern, type PostalAddress, RESOLVABLE_FIELD_TYPE_WORDS, USE_CASE_LOADERS, type UseCase, type UseCaseDashboardQuestion, type UseCaseDocumentTemplate, type UseCaseField, type UseCaseForm, type UseCaseFormField, type UseCaseMergeField, type UseCaseNotificationRule, type UseCaseNotificationTrigger, type UseCasePipeline, type UseCasePipelineStage, type UseCaseProblem, type UseCaseProvenance, type UseCaseRelationship, type UseCaseRow, type UseCaseSummary, type UseCaseTable, type UseCaseVerdict, assertUseCase, describePlaceholder, findPlaceholders, listUseCases, loadAllUseCases, loadUseCase, summarize, useCaseFor, useCaseIds, validateUseCase };