@nivaro/extension-kit 0.1.1

package/dist/imports.d.ts

@@ -0,0 +1,155 @@
+import type { Knex } from 'knex';
+export type ImportRunItemKind = 'created' | 'updated' | 'removed' | 'skipped' | 'failed';
+export interface ImportRunChange {
+    field: string;
+    from: unknown;
+    to: unknown;
+}
+export interface ImportRunItem {
+    kind: ImportRunItemKind;
+    collection?: string | null;
+    item_id?: string | number | null;
+    /** How a person names the record or the file row. */
+    label: string;
+    /** 1-based row in the file, header excluded. */
+    row?: number | null;
+    /** Why it was left out, or what went wrong. */
+    message?: string | null;
+    changes?: ImportRunChange[];
+}
+export interface ImportRunPhase {
+    key: string;
+    label: string;
+    ms: number;
+    /** Rows or records the phase handled. */
+    count?: number;
+    failed?: number;
+}
+export interface ImportRunUnmatched {
+    column: string;
+    /** 'vendor', 'purchase order key' — as a person says it. */
+    label: string;
+    /** Distinct values, first 50. */
+    values: string[];
+    distinct: number;
+    /** File rows that carry one of them. */
+    rows: number;
+    /** What the import did about it. */
+    effect: string;
+}
+export interface ImportSampleChange {
+    field: string;
+    from: unknown;
+    to: unknown;
+}
+/** What a dry run would do, with enough rows to explain itself. */
+export interface ImportSamples {
+    /** First file row per natural key that would be created (payload). */
+    creates: Array<{
+        key: string;
+        values: Record<string, unknown>;
+    }>;
+    /** Existing rows that would change, field by field. */
+    updates: Array<{
+        key: string;
+        id: unknown;
+        changes: ImportSampleChange[];
+    }>;
+    /** Rows dropped before writing — the file row number (1-based, header
+     *  excluded), the natural key when it could be built, and the reason. */
+    skipped_rows: Array<{
+        row: number;
+        key: string | null;
+        reason: string;
+    }>;
+    /** Lookup values with no match that a real run would stub-create. */
+    would_create_lookups: Array<{
+        column: string;
+        collection: string;
+        values: string[];
+    }>;
+}
+export interface ImportProcessorResult {
+    created: number;
+    updated: number;
+    unchanged: number;
+    /** Rows dropped before writing, with per-reason counts. */
+    skipped: Record<string, number>;
+    failed: number;
+    /** First line is the summary the run list shows; the rest is detail. */
+    log: string;
+    /** Present on a dry run. */
+    samples?: ImportSamples;
+    /** Records the run changed, per collection — handed to the post-run flows. */
+    affected?: Record<string, Array<string | number>>;
+    /** What the run did, for the run's detail view. */
+    report?: {
+        phases?: ImportRunPhase[];
+        unmatched?: ImportRunUnmatched[];
+        notes?: string[];
+        other?: Array<{
+            label: string;
+            count: number;
+        }>;
+    };
+    /** One entry per record created or changed and per file row left out. */
+    items?: ImportRunItem[];
+}
+export interface ImportWriteOutcome {
+    done: number;
+    failed: number;
+    /** First few failure messages, already prefixed with the job's label. */
+    failures: string[];
+    ms: number;
+}
+export interface ImportWriteJob {
+    /** Names the row in a failure message ('line 102-300001123 / 2'). */
+    label: string;
+    run: () => Promise<void>;
+}
+/** The only way a processor writes: through the items service, as the
+ *  person who queued the file. Every write tool throws on a dry run. */
+export interface ImportProcessorTools {
+    /** Read access for batched lookups. Writes go through create / update / remove. */
+    db: Knex;
+    /** value → id for one reference column, matched case-insensitively; when a
+     *  value matches several rows the lowest id wins. */
+    lookup(table: string, column: string, values: Iterable<string>): Promise<Map<string, unknown>>;
+    /** Run `fn` over `values` in chunks small enough for one statement. */
+    inChunks<T>(values: unknown[], fn: (chunk: unknown[]) => Promise<T[]>): Promise<T[]>;
+    create(collection: string, body: Record<string, unknown>): Promise<unknown>;
+    update(collection: string, id: string | number, patch: Record<string, unknown>): Promise<void>;
+    remove(collection: string, id: string | number): Promise<void>;
+    /** Run write jobs several at a time. A failed job never stops the others. */
+    runWrites(jobs: ImportWriteJob[], opts?: {
+        width?: number;
+    }): Promise<ImportWriteOutcome>;
+    /** Recompute every stored rollup on these records, once each. */
+    recalcStoredRollups(collection: string, ids: Array<string | number>): Promise<number>;
+    /** EXEC a stored procedure on its own long-running request. Returns ms. */
+    runProcedure(name: string): Promise<number>;
+}
+export interface ImportProcessorInput {
+    definition: {
+        key: string;
+        label: string | null;
+        config: Record<string, unknown>;
+    };
+    /** Parsed + header-mapped rows, staging column names as keys. */
+    rows: Array<Record<string, string>>;
+    /** Classify and report only — every write tool refuses. */
+    dryRun: boolean;
+    sampleLimit: number;
+    tools: ImportProcessorTools;
+    /** Rows classified so far, for the run's progress bar. */
+    progress(done: number, total: number): void;
+}
+/** A processor for staged imports whose file spans several collections. */
+export interface ImportProcessorDef {
+    /** `<extension>:<name>` — what `nivaro_import_definitions.processor` holds. */
+    key: string;
+    label: string;
+    description?: string;
+    run(input: ImportProcessorInput): Promise<ImportProcessorResult>;
+}
+//# sourceMappingURL=imports.d.ts.map

package/dist/imports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imports.d.ts","sourceRoot":"","sources":["../src/imports.ts"],"names":[],"mappings":"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"}

package/dist/imports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=imports.js.map

package/dist/imports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"imports.js","sourceRoot":"","sources":["../src/imports.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @nivaro/extension-kit — the contract a Nivaro extension is written against.
+ *
+ * Types: the extension context and every registration the core accepts.
+ * Helpers: the small pure functions extensions used to hand-copy from the API
+ * because `api/src` cannot be imported from an extension.
+ */
+export { databaseKey, hasColumn, resetColumnProbes } from './column-probe.js';
+export type * from './context.js';
+export type * from './flows.js';
+export type * from './hooks.js';
+export type * from './imports.js';
+export type * from './notifications.js';
+export type * from './obligations.js';
+export type * from './registrations.js';
+export { REQUESTER_COLUMNS, type RequesterTable, requesterInsertFields, requesterSelectColumns } from './requester-columns.js';
+export type * from './signals.js';
+export type * from './user.js';
+/** Type-checks an extension's default export without changing it. */
+export declare function defineExtension<T extends import('./context.js').ExtensionDefinition>(ext: T): T;
+export { createTestContext, createTestDb, type TestContext, type TestContextOptions, type TestDbState, type TestRoute } from './testing.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAC7E,mBAAmB,cAAc,CAAA;AACjC,mBAAmB,YAAY,CAAA;AAC/B,mBAAmB,YAAY,CAAA;AAC/B,mBAAmB,cAAc,CAAA;AACjC,mBAAmB,oBAAoB,CAAA;AACvC,mBAAmB,kBAAkB,CAAA;AACrC,mBAAmB,oBAAoB,CAAA;AACvC,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,EACnB,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,wBAAwB,CAAA;AAC/B,mBAAmB,cAAc,CAAA;AACjC,mBAAmB,WAAW,CAAA;AAE9B,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,CAAC,SAAS,OAAO,cAAc,EAAE,mBAAmB,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAE/F;AACD,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,SAAS,EACf,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * @nivaro/extension-kit — the contract a Nivaro extension is written against.
+ *
+ * Types: the extension context and every registration the core accepts.
+ * Helpers: the small pure functions extensions used to hand-copy from the API
+ * because `api/src` cannot be imported from an extension.
+ */
+export { databaseKey, hasColumn, resetColumnProbes } from './column-probe.js';
+export { REQUESTER_COLUMNS, requesterInsertFields, requesterSelectColumns } from './requester-columns.js';
+/** Type-checks an extension's default export without changing it. */
+export function defineExtension(ext) {
+    return ext;
+}
+export { createTestContext, createTestDb } from './testing.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAQ7E,OAAO,EACL,iBAAiB,EAEjB,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,wBAAwB,CAAA;AAI/B,qEAAqE;AACrE,MAAM,UAAU,eAAe,CAAuD,GAAM;IAC1F,OAAO,GAAG,CAAA;AACZ,CAAC;AACD,OAAO,EACL,iBAAiB,EACjB,YAAY,EAKb,MAAM,cAAc,CAAA"}

package/dist/notifications.d.ts

@@ -0,0 +1,183 @@
+export type NotifyCategory = 'mentions' | 'workflow' | 'sla' | 'watch' | 'alerts' | 'anomaly' | 'reports' | 'integrations' | 'system' | 'other';
+export type NotificationKind = 'record' | 'task' | 'approval' | 'access_request' | 'sla' | 'chat' | 'queue' | 'report' | 'alerts' | 'issue' | 'import' | 'dashboard' | 'my_work' | 'home' | 'external' | 'integration';
+export type NotificationAction = 'open' | 'complete' | 'acknowledge' | 'review' | 'approve' | 'reply';
+/** What a notification is ABOUT, and what clicking it should do. */
+export interface NotificationTargetSpec {
+    kind: NotificationKind;
+    /** record / sla: the record. approval: the approval's record. */
+    collection?: string | null;
+    /** record id, task id, approval instance id, queue / report / dashboard id. */
+    id?: string | number | null;
+    /** chat: room key. */
+    room?: string | null;
+    /** record: query string appended (addendum=…, layout=…). */
+    query?: string | null;
+    /** record: field to focus / tab to open on arrival. */
+    focus?: string | null;
+    tab?: string | null;
+    /** external: absolute URL. */
+    url?: string | null;
+    /** The primary thing a click should offer. Default 'open'. */
+    action?: NotificationAction;
+    /** Extra ids the action needs (task id for a record-kind row, …). */
+    task_id?: string | number | null;
+    instance_id?: string | number | null;
+}
+/** `nivaro_notifications.detail` — what the row is about beyond subject +
+ *  message. Diagnostic and explanatory only; never drives delivery. */
+export interface NotificationDetail {
+    changes?: Array<{
+        field: string;
+        label: string;
+        old: string;
+        new: string;
+    }>;
+    via_child?: {
+        collection: string;
+        item: string;
+        event: string;
+        label?: string | null;
+    } | null;
+    bundle?: {
+        writes: number;
+        children: string[];
+    } | null;
+    why?: {
+        kind: string;
+        text: string;
+        label?: string | null;
+        id?: string | number | null;
+    } | null;
+}
+export interface NotifyUserOptions {
+    subject: string;
+    message: string;
+    collection?: string | null;
+    item?: string | null;
+    sender?: string | null;
+    /** Defaults: inapp true, email false, sms false. */
+    channels?: {
+        inapp?: boolean;
+        email?: boolean;
+        sms?: boolean;
+    };
+    /** Explicit notification-rules category; otherwise sniffed from the subject. */
+    category?: NotifyCategory;
+    /** Skip the two "you already know" suppressions — record mutes and
+     *  presence-aware suppression — so the inbox row ALWAYS lands. The matrix,
+     *  quiet hours and suspended/redacted skips still apply. */
+    always_inbox?: boolean;
+    /** Dedicated Liquid template for the EMAIL channel (default 'notification'). */
+    template?: string;
+    template_data?: Record<string, unknown>;
+    /** Footer "You're getting this because …". */
+    why?: string | null;
+    /** What the notification is about + what a click should offer. Defaults to
+     *  the record named by collection + item. */
+    target?: NotificationTargetSpec | null;
+    /** What produced this row (the bell's "why me?"). */
+    source?: {
+        kind: string;
+        label?: string | null;
+        id?: string | number | null;
+    } | null;
+    /** Structured content stored with the row. */
+    detail?: Omit<NotificationDetail, 'why'> | null;
+    /** Internal: set on outbox re-deliveries to prevent re-enqueue loops. */
+    _retry?: boolean;
+}
+export interface NotificationDeliveryContext {
+    recipient: string;
+    subject: string;
+    message: string;
+    collection?: string;
+    item?: string | number;
+    sender?: string;
+}
+/** A custom delivery channel (SMS, Slack, Teams…). */
+export interface NotificationChannelDef {
+    id: string;
+    label: string;
+    /** Called for each notification that should be delivered via this channel. */
+    deliver(ctx: NotificationDeliveryContext): Promise<void>;
+}
+export interface ExternalNotificationSourceItem {
+    id: string | number;
+    /** What the user is watching, e.g. "Part 26824 · Main warehouse". */
+    label: string;
+    /** Secondary line, e.g. "alert when on-hand < 50". */
+    detail?: string | null;
+    is_active?: boolean;
+}
+export interface ExternalNotificationSourceGroup {
+    /** Stable key, unique per provider (e.g. 'stock-watches'). */
+    key: string;
+    /** Card section title, e.g. "Stock Planning watches". */
+    title: string;
+    description?: string;
+    /** Where the user manages these (the card renders a Manage link). */
+    manage_url?: string;
+    items: ExternalNotificationSourceItem[];
+}
+/** Contributes extension-owned subscriptions to the profile's
+ *  notification-sources card. */
+export interface NotificationSourceProvider {
+    /** Unique provider id — conventionally the extension id. */
+    id: string;
+    fetch(userId: string): Promise<ExternalNotificationSourceGroup[]>;
+}
+export interface DigestLine {
+    text: string;
+    sub?: string | null;
+    url?: string | null;
+}
+export interface DigestSection {
+    title: string;
+    lines: DigestLine[];
+}
+/** A per-user section of the daily action digest email; null = nothing today. */
+export type DigestSectionProvider = (userId: string, email: string) => Promise<DigestSection | null>;
+export type MailSampleKind = 'record' | 'history' | 'user' | 'notification' | 'none';
+export interface MailSampleOption {
+    id: string;
+    label: string;
+    hint?: string;
+}
+export interface MailRendered {
+    subject: string;
+    html: string;
+    /** Who production would send this to, with the reason each is on the list. */
+    recipients: Array<{
+        email: string;
+        reason: string;
+    }>;
+    category?: NotifyCategory;
+}
+/** An email type for the admin mail harness (preview / send with real data). */
+export interface MailTypeDef {
+    key: string;
+    label: string;
+    group: string;
+    description: string;
+    /** Liquid template name (core or extension root) — informational for
+     *  types whose builder assembles HTML itself. */
+    template: string | null;
+    category?: NotifyCategory;
+    sample: {
+        kind: MailSampleKind;
+        /** For 'record': the collection the picker browses. For 'history': the
+         *  bound collection whose instances are offered (null = any). */
+        collection?: string | null;
+        /** Extra narrowing for 'history' samples (e.g. only terminal 'canceled'). */
+        history_filter?: 'canceled' | 'any';
+        /** 'notification': subject prefix / category the sample rows are drawn from. */
+        notification_category?: NotifyCategory;
+    };
+    /** Sample rows the picker offers (most recent first). */
+    samples: (q: string) => Promise<MailSampleOption[]>;
+    /** Render for a chosen sample id (+ the recipient the harness will use). */
+    render: (sampleId: string, opts: {
+        recipientUserId?: string;
+    }) => Promise<MailRendered>;
+}
+//# sourceMappingURL=notifications.d.ts.map

package/dist/notifications.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.d.ts","sourceRoot":"","sources":["../src/notifications.ts"],"names":[],"mappings":"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"}

package/dist/notifications.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=notifications.js.map

package/dist/notifications.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.js","sourceRoot":"","sources":["../src/notifications.ts"],"names":[],"mappings":""}

package/dist/obligations.d.ts

@@ -0,0 +1,66 @@
+import type { Knex } from 'knex';
+export type ObligationOutcome = 'sent' | 'skipped' | 'failed' | 'pending' | 'overdue' | 'missing' | 'superseded';
+export type ObligationTrigger = 'transition' | 'hook' | 'flow' | 'cron' | 'reconcile' | 'manual';
+/** The decision point at which a partner starts expecting a message. */
+export interface ObligationTriggerContext {
+    collection: string;
+    item: string;
+    api: string;
+    source: 'erp_submit' | 'flow' | 'hook' | 'cron' | 'manual';
+    endpoint_path?: string | null;
+    transition_label?: string | null;
+    to_state_key?: string | null;
+    flow_name?: string | null;
+    /** The action's own declared shape — its context-query keys and skip
+     *  gates. Two actions on one endpoint are told apart by this. */
+    action_context_keys?: string[];
+    action_skip_unless_any?: string[];
+    action_skip_when_empty?: string | null;
+}
+export interface ExpectedObligation {
+    item: string;
+    due_at: Date;
+    signature?: string | null;
+    detail?: string | null;
+}
+export interface ObligationResolvePatch {
+    outcome: ObligationOutcome;
+    reason?: string | null;
+    submission_id?: number | null;
+    signature?: string | null;
+    resolved_by?: string | null;
+    detail?: unknown;
+}
+/** An outbound obligation kind: what the partner expects, how a decision
+ *  point is attributed to it, and how to derive from DATA the records the
+ *  partner is currently behind on. Core owns the ledger and the sweep; the
+ *  extension owns the sends. */
+export interface ObligationKindDef {
+    api: string;
+    kind: string;
+    collection: string;
+    label: string;
+    /** Minutes after due_at before the sweep calls an unmet expectation
+     *  overdue. Falls back to the API's skip_grace_minutes. */
+    grace_minutes?: number;
+    matches?(ctx: ObligationTriggerContext): boolean;
+    /** Records the partner is BEHIND on, derived from data alone. A returned
+     *  row means "the partner does not have this", never "this happened". A
+     *  kind's own WHERE must exclude anything whose relevant moment predates
+     *  `epoch`, or the first sweep floods `missing`. */
+    expect(database: Knex, opts: {
+        epoch: Date;
+    }): Promise<ExpectedObligation[]>;
+    /** May the sweep re-fire a `missing` row by itself? Opt-in: only ever
+     *  correct for a kind whose stored body cannot go stale. */
+    safe_to_refire?: boolean;
+    /** The send is a person's to make (a button on the record), never the
+     *  sweep's. */
+    human?: boolean;
+    /** The kind's "record" is not a business record (an API log bucket). */
+    inbound?: boolean;
+    /** The endpoint this kind's send goes to, as stored on the submission.
+     *  Required before the sweep may re-fire anything. */
+    endpoint_path?: string | null;
+}
+//# sourceMappingURL=obligations.d.ts.map

package/dist/obligations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"obligations.d.ts","sourceRoot":"","sources":["../src/obligations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAEhC,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,SAAS,GACT,QAAQ,GACR,SAAS,GACT,SAAS,GACT,SAAS,GACT,YAAY,CAAA;AAEhB,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAA;AAEhG,wEAAwE;AACxE,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAA;IAC1D,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB;qEACiE;IACjE,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC9B,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAA;IACjC,sBAAsB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACvC;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,IAAI,CAAA;IACZ,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,iBAAiB,CAAA;IAC1B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED;;;gCAGgC;AAChC,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb;+DAC2D;IAC3D,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,CAAC,GAAG,EAAE,wBAAwB,GAAG,OAAO,CAAA;IAChD;;;wDAGoD;IACpD,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE;QAAE,KAAK,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAA;IAC5E;gEAC4D;IAC5D,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;mBACe;IACf,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;0DACsD;IACtD,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B"}

package/dist/obligations.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=obligations.js.map

package/dist/obligations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"obligations.js","sourceRoot":"","sources":["../src/obligations.ts"],"names":[],"mappings":""}