@lovelaces-io/storyteller 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-type StoryLevel = "tell" | "warn" | "oops";
+/** Human-readable level labels stored in story records */
+type StoryLevel = "Information" | "Warning" | "Error";
 type StoryContextValue = Record<string, unknown> | string;
 type StoryError = {
     name?: string;
@@ -24,22 +25,27 @@ type StoryEventBase = {
         where?: StoryContextValue;
     };
     notes: StoryNote[];
+    durationMs?: number;
     error?: StoryError;
 };
-type StorySummaryOptions = {
+type ReportOptions = {
     timezone?: string;
     locale?: string;
-    verbosity?: "brief" | "normal" | "full";
-    maxNotes?: number;
+    detail?: "brief" | "normal" | "full";
+    noteLimit?: number;
     showData?: boolean;
-    colorize?: boolean;
+    colors?: boolean;
 };
-type StoryPreviewOptions = StorySummaryOptions & {
+/** @deprecated Use ReportOptions instead */
+type StorySummaryOptions = ReportOptions;
+type PreviewOptions = ReportOptions & {
     title?: string;
     level?: StoryLevel;
     error?: unknown;
 };
-type StorySummaryNote = {
+/** @deprecated Use PreviewOptions instead */
+type StoryPreviewOptions = PreviewOptions;
+type ReportNote = {
     timestamp: string;
     when: string;
     note: string;
@@ -49,22 +55,28 @@ type StorySummaryNote = {
     where?: StoryContextValue;
     error?: StoryError;
 };
-type StorySummaryData = {
+/** @deprecated Use ReportNote instead */
+type StorySummaryNote = ReportNote;
+type StoryReport = {
     title: string;
     level: StoryLevel;
     when: string;
     durationMs?: number;
     duration?: string;
     origin?: StoryEventBase["origin"];
-    notes: StorySummaryNote[];
+    notes: ReportNote[];
     error?: StoryError;
 };
-type StorySummary = {
+/** @deprecated Use StoryReport instead */
+type StorySummaryData = StoryReport;
+type FormattedReport = {
     text: string;
-    data: StorySummaryData;
+    data: StoryReport;
 };
+/** @deprecated Use FormattedReport instead */
+type StorySummary = FormattedReport;
 type StoryEvent = StoryEventBase & {
-    summarize: (options?: StorySummaryOptions) => StorySummary;
+    summarize: (options?: ReportOptions) => FormattedReport;
 };
 type AudienceMember = {
     name: string;
@@ -88,8 +100,22 @@ declare class AudienceRegistry {
     getAll(): AudienceMember[];
     /** Return only the audience members matching the given names */
     getOnly(names: string[]): AudienceMember[];
+    /** Check if an audience member is registered by name */
+    has(name: string): boolean;
+    /** List the names of all registered audience members */
+    names(): string[];
 }
-/** Core logging class that collects timestamped notes and emits them as structured story events */
+/**
+ * Collects timestamped notes and emits them as a single structured story event.
+ *
+ * @example
+ * ```ts
+ * const story = new Storyteller({ origin: { who: "api-server" } });
+ * story.note("Request received", { what: { path: "/checkout" } });
+ * story.note("Validated cart");
+ * story.tell("Checkout started");
+ * ```
+ */
 declare class Storyteller {
     readonly audience: AudienceRegistry;
     private readonly origin?;
@@ -98,21 +124,31 @@ declare class Storyteller {
         origin?: StoryEventBase["origin"];
         audiences?: AudienceMember[];
     });
-    /** Add a timestamped note with optional context (who, what, where, error) */
+    /**
+     * Add a timestamped note to the current story.
+     * @param text - What happened
+     * @param data - Optional context: who did it, what was involved, where it happened, any error
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```ts
+     * story.note("Card charged", { what: { amount: "$42" }, where: "stripe" });
+     * ```
+     */
     note(text: string, data?: NoteData): this;
     /** Clear all accumulated notes without emitting a story */
     reset(): this;
-    /** Generate a formatted summary of current notes without emitting or clearing them */
-    summarize(options?: StoryPreviewOptions): StorySummary;
-    /** Emit a story at the "tell" level (success / informational) */
+    /** Preview the current notes as a formatted report without emitting or clearing them */
+    summarize(options?: PreviewOptions): FormattedReport;
+    /** Tell a success story — everything went well */
     tell(title: string): {
         to: (...names: string[]) => void;
     };
-    /** Emit a story at the "warn" level (something was off) */
+    /** Tell a cautionary story — something was off but it's handled */
     warn(title: string): {
         to: (...names: string[]) => void;
     };
-    /** Emit a story at the "oops" level (something broke) with an optional error */
+    /** Tell an error story — something broke. Pass the error for automatic normalization. */
     oops(title: string, error?: unknown): {
         to: (...names: string[]) => void;
     };
@@ -123,29 +159,84 @@ declare class Storyteller {
     /** Deliver a story event to matching audience members */
     private deliver;
 }
-/** Generate a formatted, human-readable summary from a story event */
-declare function summarizeStory(story: StoryEventBase, options?: StorySummaryOptions): StorySummary;
+
+/**
+ * Format a story event into a human-readable report with optional colors.
+ *
+ * @param story - The story event to format
+ * @param options - Formatting options (timezone, locale, detail level, colors)
+ * @returns A FormattedReport with both text (for display) and data (structured)
+ *
+ * @example
+ * ```ts
+ * const report = formatStory(event, { colors: false, detail: "brief" });
+ * console.log(report.text);
+ * ```
+ */
+declare function formatStory(story: StoryEventBase, options?: ReportOptions): FormattedReport;
+/** Convert milliseconds into a human-readable duration string */
+declare function formatDuration(milliseconds: number): string;
+/** @deprecated Use formatStory instead */
+declare const summarizeStory: typeof formatStory;
 
 type StorytellerSharedOptions = {
     origin?: StoryEventBase["origin"];
     reset?: boolean;
 };
-/** Return a shared singleton Storyteller instance for cross-component or cross-service logging */
+/**
+ * Get or create a shared Storyteller instance for cross-component logging.
+ * First call creates the instance; subsequent calls return the same one.
+ *
+ * @param options.origin - Origin context for the shared instance
+ * @param options.reset - Create a fresh instance (useful in tests)
+ *
+ * @example
+ * ```ts
+ * // Same instance everywhere in your app
+ * const story = useStoryteller({ origin: { who: "worker" } });
+ * ```
+ */
 declare function useStoryteller(options?: StorytellerSharedOptions): Storyteller;
 
-/** Create an audience that logs stories to the browser console with color-coded grouped output */
+/**
+ * Create an audience that prints stories to the console with color-coded grouped output.
+ * Registered by default on every Storyteller instance.
+ *
+ * @example
+ * ```ts
+ * // Already included — but you can re-add after removing:
+ * story.audience.add(consoleAudience());
+ * ```
+ */
 declare function consoleAudience(): AudienceMember;
 
-/** Create an audience that persists warn and oops stories to a database via the provided insert function */
+/**
+ * Create an audience that stores warn and oops stories via your insert function.
+ * Tell-level events are filtered out to reduce noise — only warnings and errors are persisted.
+ *
+ * Note: if the insert function throws, the error is silently caught by the delivery
+ * pipeline (Promise.allSettled). Wrap your insert with try/catch to handle failures.
+ *
+ * @param insert - Function that receives the story event and stores it
+ *
+ * @example
+ * ```ts
+ * story.audience.add(
+ *   dbAudience(async (event) => {
+ *     await db.insert("story_logs", event);
+ *   })
+ * );
+ * ```
+ */
 declare function dbAudience(insert: (event: StoryEvent) => Promise<void> | void): AudienceMember;
 
 type StoryReportOptions = {
     timezone?: string;
     locale?: string;
-    verbosity?: "brief" | "normal" | "full";
-    maxNotesPerStory?: number;
+    detail?: "brief" | "normal" | "full";
+    noteLimit?: number;
     showData?: boolean;
-    colorize?: boolean;
+    colors?: boolean;
 };
 /** Generate a formatted report from an array of story events, grouped by day */
 declare function writeStoryReport(stories: StoryEventBase[], options?: StoryReportOptions): string;
@@ -163,13 +254,5 @@ declare const ANSI: {
 declare function getLevelColor(level: StoryLevel): string;
 /** Format an origin context into a human-readable path like "app / page / component" */
 declare function formatOrigin(origin?: StoryEventBase["origin"]): string | undefined;
-/** Colorize JSON output, dimming the notes section for visual hierarchy */
-declare function colorizeJsonSections(json: string, colors: {
-    base: string;
-    notes: string;
-    reset: string;
-}): string[];
-/** Count the net bracket depth change in a line (opening brackets minus closing brackets) */
-declare function countBrackets(line: string): number;
 
-export { ANSI, type AudienceMember, type StoryContextValue, type StoryError, type StoryEvent, type StoryEventBase, type StoryLevel, type StoryNote, type StoryPreviewOptions, type StoryReportOptions, type StorySummary, type StorySummaryData, type StorySummaryNote, type StorySummaryOptions, Storyteller, colorizeJsonSections, consoleAudience, countBrackets, dbAudience, formatOrigin, getLevelColor, summarizeStory, useStoryteller, writeStoryReport };
+export { ANSI, type AudienceMember, type FormattedReport, type PreviewOptions, type ReportNote, type ReportOptions, type StoryContextValue, type StoryError, type StoryEvent, type StoryEventBase, type StoryLevel, type StoryNote, type StoryPreviewOptions, type StoryReport, type StoryReportOptions, type StorySummary, type StorySummaryData, type StorySummaryNote, type StorySummaryOptions, Storyteller, consoleAudience, dbAudience, formatDuration, formatOrigin, formatStory, getLevelColor, summarizeStory, useStoryteller, writeStoryReport };