open-agreements
Version:
Open-source legal template filling CLI and library
114 lines • 5.57 kB
TypeScript
/**
* Shared fill pipeline used by all three fill paths (template, external, fieldSelector).
* Centralizes: defaults, boolean coercion, display fields, currency sanitization,
* drafting note removal, and the docx-templates createReport() call.
*/
import type { FieldDefinition } from './metadata.js';
export interface PrepareFillDataOptions {
/** User-provided values. */
values: Record<string, unknown>;
/** Field definitions from metadata. */
fields: FieldDefinition[];
/** Priority field names from metadata.priority_fields. */
priorityFieldNames?: string[];
/**
* When true, unfilled optional fields default to BLANK_PLACEHOLDER ('_______')
* so omissions are visible. When false, they default to '' (empty string).
* All fill paths use true by default.
*/
useBlankPlaceholder?: boolean;
/** Coerce boolean-typed fields to actual JS booleans for IF conditions. */
coerceBooleans?: boolean;
/**
* Optional callback for computing display fields (template-specific).
* Called after defaults and boolean coercion are applied.
*/
computeDisplayFields?: (data: Record<string, unknown>) => void;
/**
* Statutory-compliance-representation (`confirm=`) clauses in the template,
* distilled from the compiled spec. Used to derive `any_confirmation_pending`
* for the cover-page confirmation notice: true when any APPLICABLE confirm
* clause (its `condition`/`when=` gate is true, or it has none) is still
* unconfirmed (its boolean confirm field is not true). Omit for templates
* without confirm clauses.
*/
confirmClauses?: ConfirmClauseDescriptor[];
}
/** A `confirm=` clause distilled from the compiled contract spec. */
export interface ConfirmClauseDescriptor {
/** Clause id (e.g. `choice-act-counsel-notice`). */
id: string;
/** Boolean confirm field gating the in-body CONFIRM bracket. */
confirm: string;
/** Optional `when=` applicability gate field; clause is absent when false. */
condition?: string;
}
export interface FillDocxOptions {
/** Template DOCX buffer (already patched with {tags}). */
templateBuffer: Buffer;
/**
* Prepared fill data from prepareFillData(). Every `{IF <var>}` referenced by
* the template DOCX must have a corresponding key here, or docx-templates throws
* on the undefined variable. In particular, a template with a `confirm=` clause
* carries `{IF any_confirmation_pending}` (the cover notice) — prepareFillData
* derives it; direct fillDocx callers must supply it (default false).
*/
data: Record<string, unknown>;
/** Apply docx-templates smart quote normalization. */
fixSmartQuotes?: boolean;
/**
* Regex patterns for paragraphs to remove before filling.
* Paragraphs whose text matches any pattern are stripped from the DOCX.
* If a matched paragraph is the only content in a table row, the entire
* row is removed to avoid empty highlighted rows.
*
* Default: `[/\bDrafting note\b/i]` — removes Common Paper drafting notes.
* Pass `[]` to disable.
*/
stripParagraphPatterns?: RegExp[];
}
/**
* Format an ISO `YYYY-MM-DD` string as a document date ("2026-07-15" →
* "July 15, 2026").
*
* Deterministic and timezone-independent by construction: the string is split
* into year/month/day components and rendered from {@link MONTH_NAMES}. It
* NEVER constructs a `Date` — `new Date('2026-07-15')` parses as UTC midnight
* and `toLocaleDateString` can render the previous calendar day in
* negative-offset timezones — and never calls any locale/`Intl` API.
*
* Non-ISO values are returned unchanged so callers may continue supplying a
* display-ready date string (e.g. "March 20, 2026"). A strict ISO-shaped value
* is a machine-readable assertion, however, so an impossible calendar date is
* rejected rather than copied into a legal document unchanged.
*/
export declare function formatDocumentDate(value: string): string;
/**
* Return a shallow copy with metadata-declared date fields normalized for
* document display. This is intentionally safe to call at more than one
* pipeline boundary: {@link formatDocumentDate} leaves display-ready and
* non-date strings unchanged.
*/
export declare function formatDocumentDateFields(values: Record<string, unknown>, fields: FieldDefinition[], pathPrefix?: string): Record<string, unknown>;
/**
* Prepare fill data with all normalization steps:
* 1. Apply defaults for optional fields not provided
* 2. Normalize multiselect fields and derive booleans (optional)
* 3. Warn about unfilled priority fields
* 4. Coerce boolean fields (optional)
* 5. Compute display fields (optional, template-specific)
*/
export declare function prepareFillData(options: PrepareFillDataOptions): Record<string, unknown>;
/**
* Fill a DOCX template with prepared data:
* 1. Strip drafting note paragraphs (configurable, on by default)
* 2. Strip highlighting from runs with filled fields (unfilled keep their highlight)
* 3. Sanitize currency and percentage values by scanning the template buffer for
* ${field} and {field}% patterns
* 4. Call docx-templates createReport() with standard delimiters
* 5. Remove structurally empty table rows left by conditional rendering
* 6. Suppress the blank-fill placeholder on lines that already carry a rule
* 7. Return the filled buffer
*/
export declare function fillDocx(options: FillDocxOptions): Promise<Uint8Array>;
//# sourceMappingURL=fill-pipeline.d.ts.map