@samva/vite 0.8.0 → 0.9.0

package/dist/project-CiUuzKsC.d.ts

@@ -0,0 +1,271 @@
+import { EmailBrand } from "@samva/markup/compiler";
+import { AssetEntry } from "@samva/markup/email/assets";
+import { EmailDiagnostic } from "@samva/markup/email/diagnostics";
+import { RenderOptions, RenderedIrEmail, RenderedIrWhatsApp, TemplateIr } from "@samva/markup/ir";
+//#region src/layout.d.ts
+/** Directories scanned for templates when no `dir` is configured, in scan order. */
+declare const DEFAULT_TEMPLATE_DIRS: readonly ["templates", "emails"];
+/** The folder for files this package generates, relative to the project root. Gitignore it. */
+declare const SAMVA_DIR = ".samva";
+/** A project's files by root-relative POSIX path: text as strings, imported assets as bytes. */
+type ProjectFiles = Readonly<Record<string, string | Uint8Array>>;
+/**
+ * The absolute directories a project's templates live in. A configured `dir`
+ * is the only one scanned; otherwise every default directory that exists. A
+ * directory outside the root cannot be compiled, because a project's files are
+ * addressed relative to its root, so it is refused rather than half-read.
+ */
+declare const templateDirectories: (root: string, dir?: string | undefined) => Promise<readonly string[]>;
+/** Every `.tsx` file beneath the given directories, as root-relative paths, sorted. */
+declare const discoverEntries: (root: string, dirs: readonly string[]) => Promise<readonly string[]>;
+/**
+ * Read the project into the map the compiler consumes: scripts, stylesheets
+ * and JSON as text, imported assets as bytes. Hidden folders (`.samva`, `.git`)
+ * and `node_modules` are not part of a project.
+ */
+declare const readProjectFiles: (root: string) => Promise<ProjectFiles>;
+//#endregion
+//#region src/brand.d.ts
+/** Where brand records are cached, relative to the project root. */
+declare const BRAND_SNAPSHOT_DIR = ".samva/brands";
+declare const SNAPSHOT_VERSION = 1;
+/** A brand as a build compiles it, with the digest the API knows its content by. */
+interface ResolvedBrand extends EmailBrand {
+  readonly digest: string;
+}
+/** The cached copy of a brand record, written by a live fetch or `samva brands pull`. */
+interface BrandSnapshot extends ResolvedBrand {
+  readonly version: typeof SNAPSHOT_VERSION;
+  readonly name: string;
+  readonly isDefault: boolean;
+  /** ISO timestamp of the pull. */
+  readonly pulledAt: string;
+}
+type BrandWarningCode = "brand-snapshot-stale" | "brand-offline";
+interface BrandWarning {
+  readonly code: BrandWarningCode;
+  readonly message: string;
+}
+type BrandResolution = {
+  readonly ok: true;
+  /** `undefined` when the project imports no brand. */
+  readonly brand: ResolvedBrand | undefined;
+  readonly source: "live" | "snapshot" | "none";
+  readonly warnings: readonly BrandWarning[];
+} | {
+  readonly ok: false;
+  readonly message: string;
+};
+interface ResolveProjectBrandInput {
+  readonly root: string;
+  readonly files: ProjectFiles;
+  /** Project-relative theme path; `undefined` when theming is disabled. */
+  readonly themePath?: string | undefined;
+  /** Environment holding `SAMVA_API_KEY`, `SAMVA_API_URL` and `PATH`; see `loadBrandEnv`. */
+  readonly env: Readonly<Record<string, string | undefined>>;
+  /** Skip the live fetch and resolve from the cached copy. */
+  readonly offline?: boolean | undefined;
+}
+/**
+ * Resolve the brand a project's `samva:brand` import names: live when the
+ * environment's credentials reach the API, else the pulled snapshot with a
+ * warning, else a failure naming both fixes.
+ */
+declare const resolveProjectBrand: (input: ResolveProjectBrandInput) => Promise<BrandResolution>;
+/**
+ * The environment a local build resolves the brand with: the process
+ * environment plus the project's `.env` files, as the editor's dev server
+ * reads them, so `SAMVA_API_KEY` in `.env` reaches `check` and `export` too.
+ */
+declare const loadBrandEnv: (root: string) => Promise<Readonly<Record<string, string | undefined>>>;
+interface BrandResolver {
+  readonly resolve: (files: ProjectFiles, themePath: string | undefined) => Promise<BrandResolution>;
+}
+//#endregion
+//#region src/compile.d.ts
+type TemplateChannel = "email" | "sms" | "whatsapp";
+/** The channels a compiled template declares, in a fixed order. */
+declare const channelsOf: (ir: TemplateIr) => readonly TemplateChannel[];
+declare const finding: (code: string, severity: EmailDiagnostic["severity"], message: string, extra?: Partial<EmailDiagnostic>) => EmailDiagnostic;
+/** One entry that declares a template and compiled. */
+interface CompiledEntry {
+  /** The identity the definition declares for itself (`ir.template`). */
+  readonly id: string;
+  /** Project-relative path of the authored entry. */
+  readonly entryPath: string;
+  readonly ir: TemplateIr;
+  readonly fixtures: Readonly<Record<string, unknown>>;
+  readonly assets: readonly AssetEntry[];
+  /** Compile warnings. Errors leave no IR, so they are on a `FailedEntry` instead. */
+  readonly diagnostics: readonly EmailDiagnostic[];
+  readonly channels: readonly TemplateChannel[];
+}
+/** An entry that is a template but did not compile. */
+interface FailedEntry {
+  readonly entryPath: string;
+  readonly diagnostics: readonly EmailDiagnostic[];
+}
+interface CompiledProject {
+  /** Sorted by id. */
+  readonly templates: readonly CompiledEntry[];
+  /** Entries that declare a template and did not compile, sorted by path. */
+  readonly failures: readonly FailedEntry[];
+  /** Candidate entries that declare no template: ordinary modules, partials and components. */
+  readonly helpers: readonly string[];
+  /** Project-level findings: a duplicate id. */
+  readonly diagnostics: readonly EmailDiagnostic[];
+  /** Every asset the templates import, deduplicated by content. */
+  readonly assets: readonly AssetEntry[];
+}
+interface CompileProjectInput {
+  readonly files: ProjectFiles;
+  /** Candidate entries, project-relative. */
+  readonly entries: readonly string[];
+  /**
+   * Where imported assets are served from. Empty is deliberately invalid for
+   * assets: no invented serving origin. A project that imports none needs none.
+   */
+  readonly assetBase: string;
+  readonly theme?: {
+    readonly css: string;
+    readonly path: string;
+  } | undefined;
+  readonly brand?: ResolvedBrand | undefined;
+}
+/**
+ * Compile every candidate entry. An entry the compiler reports `no-template`
+ * for is a helper module, not a template; that is how a partial is told apart
+ * from a template without evaluating either. One failure stays with its entry.
+ */
+declare const compileProject: (input: CompileProjectInput) => Promise<CompiledProject>;
+/** One fixture rendered through the email channel of the template it belongs to. */
+interface RenderedFixture {
+  readonly templateId: string;
+  readonly fixture: string;
+  readonly rendered: RenderedIrEmail | undefined;
+  readonly diagnostics: readonly EmailDiagnostic[];
+}
+/**
+ * Render every fixture a template declares through its email channel. A fixture
+ * the renderer refuses is a finding on that fixture, never a thrown error, so
+ * one bad input does not take the rest of the catalog with it.
+ */
+declare const renderEmailFixtures: (entry: Pick<CompiledEntry, "id" | "ir" | "fixtures">, options?: RenderOptions) => readonly RenderedFixture[];
+/** Client-matrix findings across the fixtures that rendered. */
+declare const emailCompatibility: (entry: Pick<CompiledEntry, "ir" | "fixtures">, rendered: readonly RenderedFixture[]) => readonly EmailDiagnostic[];
+/** A channel's rendered output for one fixture, or the findings that stopped it. */
+type RenderedChannel = {
+  readonly ok: true;
+  readonly channel: "sms";
+  readonly text: string;
+} | {
+  readonly ok: true;
+  readonly channel: "whatsapp";
+  readonly message: RenderedIrWhatsApp;
+} | {
+  readonly ok: false;
+  readonly diagnostics: readonly EmailDiagnostic[];
+};
+/** Render the SMS or WhatsApp channel of one fixture. */
+declare const renderChannelFixture: (entry: Pick<CompiledEntry, "id" | "ir" | "fixtures">, channel: "sms" | "whatsapp", fixture: string, options?: RenderOptions) => RenderedChannel;
+declare const hasErrors: (diagnostics: readonly EmailDiagnostic[]) => boolean;
+//#endregion
+//#region src/project.d.ts
+interface ProjectOptions {
+  /** The project root: `theme.css`, shared imports and `.samva/` live here. Default: the working directory. */
+  readonly root?: string | undefined;
+  /**
+   * The templates directory, relative to `root` (or absolute, inside it). When set, only it is
+   * scanned; otherwise `templates/` and `emails/` are, whichever exist.
+   */
+  readonly dir?: string | undefined;
+  /**
+   * Skip the live brand fetch and use the cached copy in `.samva/brands`, as with no network.
+   */
+  readonly offline?: boolean | undefined;
+  /** Theme stylesheet relative to `root`; `false` compiles with no project theme. Default `theme.css`. */
+  readonly theme?: string | false | undefined;
+  /**
+   * Where imported assets are served from. A template that imports none needs none; an import
+   * with no base is a finding.
+   */
+  readonly assetBase?: string | undefined;
+}
+/** A project compiled: its catalog, and the findings about the project as a whole. */
+interface LoadedProject {
+  readonly root: string;
+  readonly files: ProjectFiles;
+  readonly catalog: CompiledProject;
+  /** The theme path, project-relative; `undefined` when theming is off or the file is absent. */
+  readonly themePath: string | undefined;
+  readonly brand: BrandResolution;
+  /** Brand findings and project-level findings (a duplicate id). */
+  readonly diagnostics: readonly EmailDiagnostic[];
+}
+/** Resolve the root a set of options names. */
+declare const projectRoot: (options: Pick<ProjectOptions, "root">) => string;
+/**
+ * Read, resolve the brand of, and compile every template in a project. `brands`
+ * lets a long-lived caller reuse a brand resolution between loads, and `only`
+ * limits compilation to the named project-relative entries.
+ */
+declare const loadProject: (options?: ProjectOptions, brands?: BrandResolver | undefined, only?: readonly string[] | undefined) => Promise<LoadedProject>;
+/** A live project over a directory, reloaded when its source changes. */
+interface ProjectSession {
+  readonly load: () => Promise<LoadedProject>;
+  readonly current: () => LoadedProject | undefined;
+  /** Called with the project-relative path of each changed file; `.samva/` and `node_modules` are ignored. */
+  readonly subscribe: (listener: (path: string) => void) => () => void;
+  readonly close: () => Promise<void>;
+}
+/**
+ * The authoring loop: one watcher, one brand resolver, a catalog reloaded on
+ * demand. Each `load` re-reads the project and recompiles every template, so a
+ * partial that changed reaches every template that imports it.
+ */
+declare const createProjectSession: (options?: ProjectOptions) => ProjectSession;
+interface ExportedFixture {
+  readonly fixture: string;
+  readonly html?: string | undefined;
+  readonly text?: string | undefined;
+  readonly sms?: string | undefined;
+  readonly whatsapp?: string | undefined;
+}
+interface ProjectExportReceipt {
+  readonly templates: readonly {
+    readonly id: string;
+    readonly entryPath: string;
+    readonly fixtures: readonly ExportedFixture[];
+  }[];
+  readonly assets: {
+    readonly base: string;
+    readonly assets: readonly AssetEntry[];
+  };
+  readonly diagnostics: readonly EmailDiagnostic[];
+}
+/**
+ * Where an export serves its assets from when the caller names no origin.
+ *
+ * An export writes one page at `templates/<id>/<fixture>.html` and every asset
+ * once at `assets/<content address>`, so the base a page resolves against is
+ * the path from its own directory back to that one. A template id is one path
+ * segment, so every page sits at the same depth and one base serves them all.
+ */
+declare const DEFAULT_EXPORT_ASSET_BASE = "../../assets";
+/**
+ * Render every template's fixtures to files beside the bytes of every asset they
+ * reference, with the manifest that maps each address to its file. Email
+ * fixtures write `<fixture>.html` and `<fixture>.txt`; a template's SMS and
+ * WhatsApp channels write `<fixture>.sms.txt` and `<fixture>.whatsapp.json`.
+ *
+ * A relative `assetBase` is accepted, and the written page resolves its images
+ * from the directory it sits in. Delivery keeps refusing relative references,
+ * because an inbox has no directory to resolve one against, so an export
+ * destined for sending names the https origin it will be served from instead.
+ */
+declare const exportProject: (input: ProjectOptions & {
+  readonly out: string;
+}) => Promise<ProjectExportReceipt>;
+//#endregion
+export { loadBrandEnv as A, renderChannelFixture as C, BrandSnapshot as D, BrandResolution as E, discoverEntries as F, readProjectFiles as I, templateDirectories as L, DEFAULT_TEMPLATE_DIRS as M, ProjectFiles as N, BrandWarning as O, SAMVA_DIR as P, hasErrors as S, BRAND_SNAPSHOT_DIR as T, TemplateChannel as _, ProjectOptions as a, emailCompatibility as b, exportProject as c, CompileProjectInput as d, CompiledEntry as f, RenderedFixture as g, RenderedChannel as h, ProjectExportReceipt as i, resolveProjectBrand as j, ResolvedBrand as k, loadProject as l, FailedEntry as m, ExportedFixture as n, ProjectSession as o, CompiledProject as p, LoadedProject as r, createProjectSession as s, DEFAULT_EXPORT_ASSET_BASE as t, projectRoot as u, channelsOf as v, renderEmailFixtures as w, finding as x, compileProject as y };
+//# sourceMappingURL=project-CiUuzKsC.d.ts.map