aurival 0.1.0

package/dist/bot.js

@@ -0,0 +1,278 @@
+/** The developer-facing surface: declare commands, call run(), we hold the socket. */
+import { Auth, KeyFile, machineLabel, pair, resolveHost } from './auth.js';
+import { AurivalError, RateLimitError } from './errors.js';
+import { Context, Event } from './events.js';
+import { DEFAULT_HOST, HttpClient, defaultLogger } from './http.js';
+import { Socket } from './socket.js';
+/** How long a clean shutdown waits for handlers that are still running (SDK-32). */
+export const SHUTDOWN_GRACE_MS = 10_000;
+// Mirrors the server's own normalisation (commands.go) so `Ping` finds the
+// handler for the `ping` that comes back on the wire. Not validation.
+function lookupKey(name) {
+    return name.trim().toLowerCase();
+}
+/**
+ * Load the key file, or pair this machine and save one.
+ *
+ * `Bot.start` and `aurival init` both come through here, so the code and the
+ * fingerprint print identically either way (SDK-43) — the printout is the thing
+ * a developer compares in the app, and two spellings of it would drift.
+ */
+export async function ensurePaired(http, keyFile, host, log, signal) {
+    const loaded = await keyFile.load();
+    if (loaded !== null)
+        return { ...loaded, paired: false };
+    const { key, machine } = await pair(http, {
+        machineLabel: machineLabel(),
+        host,
+        out: (line) => process.stdout.write(line + '\n'),
+        logger: log,
+        signal,
+    });
+    await keyFile.save(key, machine);
+    return { key, machine, paired: true };
+}
+/**
+ * The one door to command sync, so the lane that syncs is always the lane that
+ * reports. Both `Bot` call sites go through here.
+ *
+ * Exported for the tests, not from `index.ts` — the package's export list
+ * mirrors Python's `__all__` (SDK-7) and this is not on it.
+ */
+export async function syncCommandsAndReport(http, bot, payload, log) {
+    reportConflicts(await http.syncCommands(bot, payload), log);
+}
+/**
+ * One warning line per shadowed chat (S11). Silently dropping `conflicts` is
+ * the silence the field exists to end: the developer whose command never fires.
+ *
+ * The wire carries chat references and deliberately not the other bot
+ * (server.go's handleReplaceCommands), so the chat id is all a line can name.
+ */
+export function reportConflicts(response, log) {
+    const rows = response['data'];
+    if (!Array.isArray(rows))
+        return;
+    for (const row of rows) {
+        if (typeof row !== 'object' || row === null)
+            continue;
+        const record = row;
+        const name = typeof record['name'] === 'string' ? record['name'] : '';
+        const conflicts = record['conflicts'];
+        if (!Array.isArray(conflicts))
+            continue;
+        for (const chat of conflicts) {
+            if (typeof chat !== 'string' || chat === '')
+                continue;
+            log.warn(`/${name} is shadowed by another bot in ${chat}, so it will not reach you there`);
+        }
+    }
+}
+/**
+ * A bot. Register commands, then `run()`.
+ *
+ * First run pairs this machine: it prints a code, you approve it in the app, and
+ * the key lands in ./.aurival/. Every later run just starts.
+ */
+export class Bot {
+    #registered = new Map();
+    #inflight = new Set();
+    #log;
+    #host;
+    #keyPath;
+    #errorHook = null;
+    #http = null;
+    constructor(options = {}) {
+        this.#log = options.logger ?? defaultLogger();
+        this.#host = options.host;
+        this.#keyPath = options.keyPath;
+    }
+    command(name, second, third) {
+        const description = typeof second === 'string' ? second : '';
+        const handler = typeof second === 'string' ? third : second;
+        if (handler === undefined)
+            throw new AurivalError(`command(${name}) needs a handler`);
+        this.#registered.set(lookupKey(name), { command: { name, description }, handler });
+    }
+    /**
+     * Called with (error, context | null) for anything the SDK caught for you: a
+     * handler that threw, a `problem` frame, a backlog overflow.
+     */
+    onError(fn) {
+        this.#errorHook = fn;
+    }
+    // -- running -----------------------------------------------------------
+    /** Installs signal handlers and runs until SIGINT/SIGTERM or something fatal. */
+    async run() {
+        const controller = new AbortController();
+        const stop = () => controller.abort();
+        process.on('SIGINT', stop);
+        process.on('SIGTERM', stop);
+        try {
+            await this.start(controller.signal);
+        }
+        finally {
+            process.off('SIGINT', stop);
+            process.off('SIGTERM', stop);
+        }
+    }
+    async start(signal) {
+        const host = this.#host ?? resolveHost();
+        if (host !== DEFAULT_HOST) {
+            // Printed, not logged: a redirected host is the first thing to check when
+            // nothing works, and a logger set to WARNING would hide it.
+            process.stdout.write(`aurival: using ${host}\n`);
+        }
+        const abort = signal ?? new AbortController().signal;
+        const unauth = new HttpClient(host, null, this.#log);
+        const keyFile = new KeyFile(this.#keyPath ?? null);
+        const { key, machine } = await ensurePaired(unauth, keyFile, host, this.#log, abort);
+        // The key file's own path, so a `key_revoked` says which file to remove
+        // (S7) — including when AURIVAL_KEY_PATH put it somewhere unexpected.
+        const auth = new Auth(unauth, key, machine, this.#log, keyFile.path);
+        const http = new HttpClient(host, auth, this.#log);
+        this.#http = http;
+        const syncRetry = await this.#syncCommands(http, machine.bot, abort);
+        const socket = new Socket(http, auth, {
+            dispatch: (event) => this.#dispatch(event),
+            onProblem: (problem) => {
+                void this.#callErrorHook(problem, null);
+            },
+            logger: this.#log,
+        });
+        try {
+            await socket.run(abort);
+        }
+        finally {
+            syncRetry?.cancel();
+            await this.#drainHandlers();
+        }
+    }
+    /** A bounded wait, then go anyway. A clean close earns no `bye`, correctly. */
+    async #drainHandlers() {
+        if (this.#inflight.size === 0)
+            return;
+        await Promise.race([
+            Promise.allSettled([...this.#inflight]),
+            new Promise((resolve) => setTimeout(resolve, SHUTDOWN_GRACE_MS)),
+        ]);
+    }
+    // -- command sync ------------------------------------------------------
+    /**
+     * Sync on every run. A rate limit does NOT take the bot offline (SDK-35):
+     * command rows are durable, so we connect with whatever the server already has
+     * and land the sync in the background.
+     */
+    async #syncCommands(http, bot, signal) {
+        const payload = [...this.#registered.values()].map((r) => ({
+            name: r.command.name,
+            description: r.command.description,
+        }));
+        try {
+            await syncCommandsAndReport(http, bot, payload, this.#log);
+            return null;
+        }
+        catch (exc) {
+            if (!(exc instanceof RateLimitError))
+                throw exc;
+            this.#log.warn(`command sync is rate limited (${exc.code}); connecting with the server's ` +
+                `current set and retrying in the background`);
+            const controller = new AbortController();
+            void this.#retrySync(http, bot, payload, exc, controller.signal, signal);
+            return { cancel: () => controller.abort() };
+        }
+    }
+    async #retrySync(http, bot, payload, first, cancelled, stopping) {
+        let delayMs = (first.retry_after ?? 60) * 1000;
+        for (;;) {
+            if (await sleepUntilAborted(delayMs, cancelled, stopping))
+                return;
+            try {
+                // The background lane reports conflicts too: a bot whose first sync was
+                // rate limited must not be the one bot that never hears about them.
+                await syncCommandsAndReport(http, bot, payload, this.#log);
+            }
+            catch (exc) {
+                if (exc instanceof RateLimitError) {
+                    delayMs = (exc.retry_after ?? 60) * 1000;
+                    continue;
+                }
+                if (exc instanceof AurivalError) {
+                    this.#log.error(`command sync failed: ${exc.message}`);
+                    return;
+                }
+                throw exc;
+            }
+            process.stdout.write('aurival: command sync landed\n');
+            return;
+        }
+    }
+    // -- dispatch ----------------------------------------------------------
+    async #dispatch(event) {
+        const work = this.#handle(event);
+        this.#inflight.add(work);
+        try {
+            await work;
+        }
+        finally {
+            this.#inflight.delete(work);
+        }
+    }
+    /**
+     * One event. Runs the handler, never lets it take the bot down (SDK-16).
+     *
+     * Note what is NOT in this frame: no key, no seed, no token.
+     */
+    async #handle(event) {
+        if (event.type !== 'command.invoked')
+            return;
+        const name = typeof event.data['command'] === 'string' ? event.data['command'] : '';
+        const registered = this.#registered.get(lookupKey(name));
+        if (registered === undefined) {
+            // The server routes by its own declared set, so this is a stale sync or a
+            // name we just removed. Not an error.
+            this.#log.debug(`no handler for command ${JSON.stringify(name)}`);
+            return;
+        }
+        if (this.#http === null)
+            return;
+        const ctx = Context.fromEvent(event, this.#http);
+        try {
+            await registered.handler(ctx);
+        }
+        catch (exc) {
+            // One bad command must not take the bot offline (SDK-16).
+            this.#log.error(`handler for ${JSON.stringify(name)} threw: ${exc instanceof Error ? (exc.stack ?? exc.message) : String(exc)}`);
+            await this.#callErrorHook(exc, ctx);
+        }
+    }
+    async #callErrorHook(error, ctx) {
+        if (this.#errorHook === null)
+            return;
+        try {
+            await this.#errorHook(error, ctx);
+        }
+        catch (exc) {
+            // An error hook that throws is not an outage either.
+            this.#log.error(`error hook threw: ${exc instanceof Error ? exc.message : String(exc)}`);
+        }
+    }
+}
+/** Resolves true if either signal fired first — a wait must never outlive a SIGINT. */
+function sleepUntilAborted(ms, a, b) {
+    if (a.aborted || b.aborted)
+        return Promise.resolve(true);
+    return new Promise((resolve) => {
+        const done = (value) => {
+            clearTimeout(timer);
+            a.removeEventListener('abort', onAbort);
+            b.removeEventListener('abort', onAbort);
+            resolve(value);
+        };
+        const onAbort = () => done(true);
+        const timer = setTimeout(() => done(false), ms);
+        a.addEventListener('abort', onAbort, { once: true });
+        b.addEventListener('abort', onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=bot.js.map

package/dist/bot.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * `aurival init` (SDK-43): from an empty folder to a running bot in one command.
+ *
+ * One subcommand and `--help`, nothing else. The pairing printout is `run()`'s
+ * own, through `ensurePaired`, so the code and fingerprint a developer compares
+ * in the app are the same lines either way.
+ */
+export declare const USAGE = "aurival \u2014 write a bot for Aurival\n\nusage:\n  aurival init     pair this machine and write a starter bot in this folder\n  aurival --help   this\n\ninit writes bot.ts when the folder already has TypeScript (a tsconfig.json),\nand bot.js otherwise, so the file it names is one you can actually run. It\nnever overwrites an existing bot file.\n";
+/**
+ * The one rule, stated so it can be applied: TypeScript if the folder already
+ * has a tsconfig.json, plain JS otherwise. A folder with no TS toolchain gets a
+ * file `node` runs as it stands — a `bot.ts` there would be a scaffold whose
+ * printed next step does not work.
+ */
+export declare function starterFilename(dir: string): 'bot.ts' | 'bot.js';
+/** The README's bot, verbatim in behaviour: declare /ping, answer pong. */
+export declare function starterSource(filename: string): string;
+export interface CliIO {
+    cwd: string;
+    out: (line: string) => void;
+    err: (line: string) => void;
+}
+/** Returns the process exit code. Never calls `process.exit` itself. */
+export declare function main(argv: string[], io?: CliIO): Promise<number>;
+export declare function init(io: CliIO): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;GAMG;AAUH,eAAO,MAAM,KAAK,iWASjB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAEhE;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAetD;AAED,MAAM,WAAW,KAAK;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAUD,wEAAwE;AACxE,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBnF;AAED,wBAAsB,IAAI,CAAC,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CA8CrD"}

package/dist/cli.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+/**
+ * `aurival init` (SDK-43): from an empty folder to a running bot in one command.
+ *
+ * One subcommand and `--help`, nothing else. The pairing printout is `run()`'s
+ * own, through `ensurePaired`, so the code and fingerprint a developer compares
+ * in the app are the same lines either way.
+ */
+import { existsSync, realpathSync } from 'node:fs';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { KeyFile, resolveHost } from './auth.js';
+import { ensurePaired } from './bot.js';
+import { HttpClient, defaultLogger } from './http.js';
+export const USAGE = `aurival — write a bot for Aurival
+
+usage:
+  aurival init     pair this machine and write a starter bot in this folder
+  aurival --help   this
+
+init writes bot.ts when the folder already has TypeScript (a tsconfig.json),
+and bot.js otherwise, so the file it names is one you can actually run. It
+never overwrites an existing bot file.
+`;
+/**
+ * The one rule, stated so it can be applied: TypeScript if the folder already
+ * has a tsconfig.json, plain JS otherwise. A folder with no TS toolchain gets a
+ * file `node` runs as it stands — a `bot.ts` there would be a scaffold whose
+ * printed next step does not work.
+ */
+export function starterFilename(dir) {
+    return existsSync(path.join(dir, 'tsconfig.json')) ? 'bot.ts' : 'bot.js';
+}
+/** The README's bot, verbatim in behaviour: declare /ping, answer pong. */
+export function starterSource(filename) {
+    const imports = filename.endsWith('.ts')
+        ? "import { Bot, type Context } from 'aurival';"
+        : "import { Bot } from 'aurival';";
+    const ctx = filename.endsWith('.ts') ? '(ctx: Context)' : '(ctx)';
+    return `${imports}
+
+const bot = new Bot();
+
+bot.command('ping', 'Check that the bot is alive', async ${ctx} => {
+  await ctx.reply('pong');
+});
+
+bot.run();
+`;
+}
+function defaultIO() {
+    return {
+        cwd: process.cwd(),
+        out: (line) => process.stdout.write(line + '\n'),
+        err: (line) => process.stderr.write(line + '\n'),
+    };
+}
+/** Returns the process exit code. Never calls `process.exit` itself. */
+export async function main(argv, io = defaultIO()) {
+    const [command, ...rest] = argv;
+    if (command === undefined || command === '--help' || command === '-h') {
+        io.out(USAGE);
+        return command === undefined ? 2 : 0;
+    }
+    if (command !== 'init') {
+        io.err(`aurival: unknown command ${JSON.stringify(command)}\n`);
+        io.err(USAGE);
+        return 2;
+    }
+    if (rest.length > 0) {
+        io.err(`aurival: init takes no arguments, got ${JSON.stringify(rest.join(' '))}`);
+        return 2;
+    }
+    return init(io);
+}
+export async function init(io) {
+    const filename = starterFilename(io.cwd);
+    const target = path.join(io.cwd, filename);
+    // Checked BEFORE pairing on purpose: pairing costs the developer a trip to
+    // their phone, and burning one to then refuse would be rude.
+    if (existsSync(target)) {
+        io.err(`aurival: ${filename} already exists here, so init has nothing to do.`);
+        io.err('Delete it first, or run init in an empty folder.');
+        return 1;
+    }
+    const host = resolveHost();
+    const log = defaultLogger();
+    const keyFile = new KeyFile(null);
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+    try {
+        const { paired } = await ensurePaired(new HttpClient(host, null, log), keyFile, host, log, controller.signal);
+        if (!paired)
+            io.out(`aurival: this machine is already paired (${keyFile.path}).`);
+    }
+    finally {
+        process.off('SIGINT', stop);
+        process.off('SIGTERM', stop);
+    }
+    // 'wx': if something raced us to the name between the check above and here,
+    // we still refuse rather than overwrite.
+    await fs.writeFile(target, starterSource(filename), { encoding: 'utf8', flag: 'wx' });
+    // The TS line names a runner we cannot promise is installed: a tsconfig.json
+    // says the folder is TypeScript, not that `tsx` is there. Hedged rather than
+    // stated, so the one next step is never a command that just fails.
+    io.out(filename === 'bot.ts'
+        ? `Wrote ${filename}. Next: run it with your TypeScript runner, for example npx tsx ${filename}`
+        : `Wrote ${filename}. Next: node ${filename}`);
+    return 0;
+}
+// Only when this file is the entry point, so importing it in a test is inert.
+// Through realpath and pathToFileURL because npm installs a bin as a SYMLINK in
+// node_modules/.bin, and a raw string compare misses that by exactly one hop —
+// `npx aurival init` would then print nothing and exit 0.
+function invokedDirectly() {
+    const entry = process.argv[1];
+    if (entry === undefined)
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(entry)).href;
+    }
+    catch {
+        return false;
+    }
+}
+if (invokedDirectly()) {
+    main(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    }, (exc) => {
+        process.stderr.write(`aurival: ${exc instanceof Error ? exc.message : String(exc)}\n`);
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,140 @@
+/**
+ * ERRORS-V1 as JavaScript errors.
+ *
+ * One class per `type` (§1), then one subclass per `code` the SDK acts on
+ * (errors_v1.go's `errCatalogue`, the closed catalogue). `fromEnvelope` turns a
+ * wire envelope into the right instance and never throws itself.
+ */
+/** Base for everything this SDK throws. */
+export declare class AurivalError extends Error {
+    constructor(message: string);
+}
+/** A network fault: dial refused, DNS, reset. Never an undici exception. */
+export declare class TransportError extends AurivalError {
+}
+/** The server said something we cannot parse as the documented envelope. */
+export declare class ProtocolError extends AurivalError {
+}
+export interface AurivalAPIErrorInit {
+    type: string;
+    code: string;
+    message: string;
+    doc_url: string;
+    request_id?: string | null;
+    retry_after?: number | null;
+    status?: number | null;
+}
+/** One ERRORS-V1 envelope. Every instance carries `code` and `doc_url`. */
+export declare class AurivalAPIError extends AurivalError {
+    readonly type: string;
+    readonly code: string;
+    readonly doc_url: string;
+    readonly request_id: string | null;
+    readonly retry_after: number | null;
+    readonly status: number | null;
+    constructor(init: AurivalAPIErrorInit);
+}
+/** `authentication_error` — 401, re-sign and retry once. */
+export declare class AuthenticationError extends AurivalAPIError {
+}
+/** `invalid_request_error` — 400/404/409, never retry. */
+export declare class InvalidRequestError extends AurivalAPIError {
+}
+/** `permission_error` — 403, never retry. */
+export declare class PermissionDeniedError extends AurivalAPIError {
+}
+/** `rate_limit_error` — 429, honour `Retry-After`. */
+export declare class RateLimitError extends AurivalAPIError {
+}
+/** `api_error` — 5xx, our fault, retry with backoff. */
+export declare class APIError extends AurivalAPIError {
+}
+export declare class AccessTokenExpired extends AuthenticationError {
+}
+export declare class AccessTokenInvalid extends AuthenticationError {
+}
+export declare class KeyRevoked extends AuthenticationError {
+}
+export declare class BadAssertion extends AuthenticationError {
+}
+export declare class AssertionExpired extends AuthenticationError {
+}
+export declare class AssertionReplay extends AuthenticationError {
+}
+export declare class BadProof extends AuthenticationError {
+}
+export declare class BadPublicKey extends AuthenticationError {
+}
+export declare class KeyAlreadyPaired extends AuthenticationError {
+}
+export declare class NotFound extends InvalidRequestError {
+}
+export declare class InvalidCommandName extends InvalidRequestError {
+}
+export declare class EmptyText extends InvalidRequestError {
+}
+export declare class TextTooLong extends InvalidRequestError {
+}
+export declare class InvalidJSON extends InvalidRequestError {
+}
+export declare class ParameterMissing extends InvalidRequestError {
+}
+export declare class ParameterInvalid extends InvalidRequestError {
+}
+export declare class UnknownParameter extends InvalidRequestError {
+}
+export declare class IdempotencyKeyReused extends InvalidRequestError {
+}
+export declare class IdempotencyKeyInvalid extends InvalidRequestError {
+}
+export declare class BotLinkNotAllowed extends InvalidRequestError {
+}
+export declare class SessionSuperseded extends InvalidRequestError {
+}
+export declare class FrameTooLarge extends InvalidRequestError {
+}
+export declare class FrameInvalid extends InvalidRequestError {
+}
+export declare class UnknownOperation extends InvalidRequestError {
+}
+export declare class AckUnknownEvent extends InvalidRequestError {
+}
+/**
+ * `too_many_problems` (SDK-39). BA-R23 was ruled and has since landed on main
+ * (`a522dcb4`), so this is a real row rather than a placeholder.
+ */
+export declare class TooManyProblems extends InvalidRequestError {
+}
+export declare class BotSuspended extends PermissionDeniedError {
+}
+export declare class BotPlaygroundOnly extends PermissionDeniedError {
+}
+export declare class RateLimited extends RateLimitError {
+}
+export declare class PairRateLimited extends RateLimitError {
+}
+export declare class SyncRateLimited extends RateLimitError {
+}
+export declare class InternalError extends APIError {
+}
+export declare class ServerRestarting extends APIError {
+}
+export declare class IdleTimeout extends APIError {
+}
+export declare const DOC_URL_PREFIX = "https://bots.aurival.com/docs/errors#";
+export type AurivalAPIErrorClass = new (init: AurivalAPIErrorInit) => AurivalAPIError;
+export declare const TYPE_CLASSES: Readonly<Record<string, AurivalAPIErrorClass>>;
+export declare const CODE_CLASSES: Readonly<Record<string, AurivalAPIErrorClass>>;
+export interface FromEnvelopeOptions {
+    status?: number | null;
+    retryAfter?: number | null;
+}
+/**
+ * Build an error from an ERRORS-V1 envelope.
+ *
+ * `payload` is the whole body/frame data: `{"error": {...}}` or already the
+ * inner object. Unknown code -> its type's class. Unknown type -> the base
+ * `AurivalAPIError`. Never throws.
+ */
+export declare function fromEnvelope(payload: Record<string, unknown>, options?: FromEnvelopeOptions): AurivalAPIError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

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