@kindgi/api 0.0.0-bootstrap.0 → 0.1.0

package/dist/webhook-endpoint-binding.d.ts

@@ -0,0 +1,230 @@
+import type { Cursor, EnvName, ProjectId, RunId, TenantId, Timestamp, WebhookDeliveryId, WebhookEndpointId, WebhookEventId } from '@kindgi/types';
+/**
+ * Outbound webhook endpoints: URLs the platform sends signed events to,
+ * such as `run.finished` when a run completes, fails or is cancelled.
+ * The inverse of `/v1/webhooks`, which are inbound triggers.
+ *
+ * Caller-plugged: the runtime owns storage, secrets, the delivery queue
+ * and the HTTP sender. This package defines the contract and the wire
+ * shapes, and mounts `/v1/webhook-endpoints` when a binding is supplied.
+ *
+ * **Secrets.** An endpoint's signing secret is shared with the receiver,
+ * so it lives where the deployment's other secrets do: the endpoint holds
+ * a reference (`secretRef`, like a provider's `secret_ref`), never the
+ * value. The caller stores the secret first (its own `.env` in
+ * development, the secrets store in production; `generate-secret` makes
+ * a strong one) and registers the endpoint with its name. The binding
+ * resolves it at tenant scope to sign each delivery, and checks on
+ * create and update that it exists and is strong (`whsec_` + base64 of
+ * at least 24 bytes, or the bare base64). Rotating is rotating that
+ * secret; while a store keeps the previous version, deliveries carry a
+ * signature for each version less than a day old. Deliveries are signed
+ * per `@kindgi/crypto` `signWebhook`; receivers verify with
+ * `verifyWebhook` or any Standard Webhooks library.
+ *
+ * **Delivery.** At least once: receivers deduplicate on the event id
+ * (the `webhook-id` header). Every method is tenant-scoped.
+ */
+export interface WebhookEndpointBinding {
+    /**
+     * Register an endpoint. The route has checked the body's shape and
+     * that `url` is an absolute http(s) URL; the binding applies the
+     * deployment's URL policy (e.g. https only, no private addresses) and
+     * answers `url-refused` with a reason, and checks the secret behind
+     * `secretRef` (`secret-not-found`, `secret-too-weak`).
+     */
+    create(input: WebhookEndpointCreateInput): Promise<WebhookEndpointCreateOutcome>;
+    list(input: WebhookEndpointListInput): Promise<WebhookEndpointPage>;
+    /** `null` when unknown or unregistered; the route answers 404. */
+    get(input: WebhookEndpointRef): Promise<WebhookEndpoint | null>;
+    update(input: WebhookEndpointUpdateInput): Promise<WebhookEndpointUpdateOutcome>;
+    /**
+     * Soft delete: the endpoint stops receiving events and its pending
+     * deliveries are abandoned. `{ unregistered: false }` when it was
+     * unknown or already unregistered.
+     */
+    unregister(input: WebhookEndpointRef): Promise<{
+        readonly unregistered: boolean;
+    }>;
+    /** The endpoint's deliveries, newest first. */
+    listDeliveries(input: WebhookDeliveryListInput): Promise<WebhookDeliveryListOutcome>;
+    /** Queue a delivery again now, whatever its status; attempts start over. */
+    redeliver(input: WebhookDeliveryRef): Promise<WebhookDeliveryOutcome>;
+    /** Queue a `webhook.test` event to the endpoint, to check the receiver end to end. */
+    sendTest(input: WebhookEndpointRef): Promise<WebhookDeliveryOutcome>;
+}
+/** Event types an endpoint can subscribe to. */
+export declare const WEBHOOK_EVENT_TYPES: readonly ["run.finished"];
+export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
+/**
+ * Which events reach the endpoint. Every field narrows; absent fields
+ * don't. `run.finished` is sent for top-level runs only (never for a
+ * child run, such as an agent step's turn).
+ */
+export interface WebhookEndpointFilter {
+    /** Only runs in this project. */
+    readonly projectId?: ProjectId;
+    /** Only runs of these flows (`flowId`, any version). */
+    readonly flowIds?: readonly string[];
+    /** Dry runs are left out unless this is `true`. */
+    readonly includeDryRuns?: boolean;
+}
+export interface WebhookEndpoint {
+    readonly endpointId: WebhookEndpointId;
+    readonly url: string;
+    readonly events: readonly WebhookEventType[];
+    readonly filter: WebhookEndpointFilter;
+    readonly description: string | null;
+    /** Where the signing secret is kept; the value never leaves the store. */
+    readonly secretRef: WebhookSecretRef;
+    readonly createdAt: Timestamp;
+    readonly updatedAt: Timestamp;
+}
+/**
+ * A secret by name in the deployment's secrets store, resolved at tenant
+ * scope — the same shape as a provider's `secret_ref`.
+ */
+export interface WebhookSecretRef {
+    readonly envName: EnvName;
+    readonly name: string;
+}
+export interface WebhookEndpointRef {
+    readonly tenantId: TenantId;
+    readonly endpointId: WebhookEndpointId;
+}
+export interface WebhookEndpointCreateInput {
+    readonly tenantId: TenantId;
+    readonly url: string;
+    readonly events: readonly WebhookEventType[];
+    readonly filter: WebhookEndpointFilter;
+    readonly secretRef: WebhookSecretRef;
+    readonly description?: string;
+}
+export interface WebhookEndpointListInput {
+    readonly tenantId: TenantId;
+    readonly limit: number;
+    readonly cursor?: Cursor;
+}
+export interface WebhookEndpointPage {
+    readonly data: readonly WebhookEndpoint[];
+    readonly nextCursor?: Cursor;
+}
+/** Fields to change; absent fields are kept. `description: null` clears it. */
+export interface WebhookEndpointUpdateInput extends WebhookEndpointRef {
+    readonly url?: string;
+    readonly events?: readonly WebhookEventType[];
+    readonly filter?: WebhookEndpointFilter;
+    readonly secretRef?: WebhookSecretRef;
+    readonly description?: string | null;
+}
+/** Why an endpoint can't be saved as asked. */
+export type WebhookEndpointRefusal = {
+    readonly kind: 'url-refused';
+    readonly reason: string;
+} | {
+    readonly kind: 'project-not-found';
+    readonly projectId: ProjectId;
+}
+/** No secret by that name (at tenant scope) in the store. */
+ | {
+    readonly kind: 'secret-not-found';
+    readonly secretRef: WebhookSecretRef;
+}
+/** The secret is not `whsec_` + base64 of at least 24 bytes (or that base64 alone). */
+ | {
+    readonly kind: 'secret-too-weak';
+    readonly secretRef: WebhookSecretRef;
+};
+export type WebhookEndpointCreateOutcome = {
+    readonly kind: 'ok';
+    readonly endpoint: WebhookEndpoint;
+} | WebhookEndpointRefusal;
+export type WebhookEndpointUpdateOutcome = {
+    readonly kind: 'ok';
+    readonly endpoint: WebhookEndpoint;
+} | {
+    readonly kind: 'not-found';
+} | WebhookEndpointRefusal;
+/**
+ * A finished top-level run, as `run.finished` carries it: the run's
+ * identity and outcome, never its input or output. Field names match
+ * `GET /v1/runs/:runId`.
+ */
+export interface FinishedRun {
+    readonly id: RunId;
+    readonly projectId: ProjectId;
+    readonly flowId: string;
+    readonly flowVersion: string;
+    readonly status: 'completed' | 'failed' | 'cancelled';
+    readonly dryRun: boolean;
+    /** Why the run failed or was cancelled; `null` when it completed. */
+    readonly failureMessage: string | null;
+    readonly createdAt: Timestamp;
+    readonly completedAt: Timestamp;
+}
+export interface RunFinishedEvent {
+    readonly id: WebhookEventId;
+    readonly type: 'run.finished';
+    readonly createdAt: Timestamp;
+    readonly data: {
+        readonly run: FinishedRun;
+    };
+}
+/** Sent only by `POST /v1/webhook-endpoints/:endpointId/test`. */
+export interface WebhookTestEvent {
+    readonly id: WebhookEventId;
+    readonly type: 'webhook.test';
+    readonly createdAt: Timestamp;
+    readonly data: {
+        readonly endpointId: WebhookEndpointId;
+    };
+}
+/** The JSON body of every webhook request. */
+export type WebhookEvent = RunFinishedEvent | WebhookTestEvent;
+/**
+ * `pending`: waiting for its next attempt. `delivered`: the endpoint
+ * answered 2xx. `failed`: every attempt failed, or the endpoint was
+ * unregistered first; `redeliver` queues it again.
+ */
+export declare const WEBHOOK_DELIVERY_STATUSES: readonly ["pending", "delivered", "failed"];
+export type WebhookDeliveryStatus = (typeof WEBHOOK_DELIVERY_STATUSES)[number];
+export interface WebhookDelivery {
+    readonly deliveryId: WebhookDeliveryId;
+    readonly endpointId: WebhookEndpointId;
+    readonly event: WebhookEvent;
+    readonly status: WebhookDeliveryStatus;
+    readonly attempts: number;
+    /** When the next attempt is due; `null` unless `pending`. */
+    readonly nextAttemptAt: Timestamp | null;
+    readonly lastAttemptAt: Timestamp | null;
+    /** HTTP status of the last attempt; `null` when it got no response. */
+    readonly lastResponseStatus: number | null;
+    /** Why the last attempt failed (`timeout`, `connection-refused`, `url-refused`, …). */
+    readonly lastError: string | null;
+    readonly createdAt: Timestamp;
+    readonly deliveredAt: Timestamp | null;
+}
+export interface WebhookDeliveryRef extends WebhookEndpointRef {
+    readonly deliveryId: WebhookDeliveryId;
+}
+export interface WebhookDeliveryListInput extends WebhookEndpointRef {
+    readonly limit: number;
+    readonly cursor?: Cursor;
+    readonly status?: WebhookDeliveryStatus;
+}
+export type WebhookDeliveryListOutcome = {
+    readonly kind: 'ok';
+    readonly data: readonly WebhookDelivery[];
+    readonly nextCursor?: Cursor;
+} | {
+    readonly kind: 'not-found';
+};
+export type WebhookDeliveryOutcome = {
+    readonly kind: 'ok';
+    readonly delivery: WebhookDelivery;
+} | {
+    readonly kind: 'not-found';
+} | {
+    readonly kind: 'delivery-not-found';
+};
+//# sourceMappingURL=webhook-endpoint-binding.d.ts.map

package/dist/webhook-endpoint-binding.d.ts.map

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

package/dist/webhook-endpoint-binding.js

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/** Event types an endpoint can subscribe to. */
+export const WEBHOOK_EVENT_TYPES = ['run.finished'];
+// ---------- deliveries ----------
+/**
+ * `pending`: waiting for its next attempt. `delivered`: the endpoint
+ * answered 2xx. `failed`: every attempt failed, or the endpoint was
+ * unregistered first; `redeliver` queues it again.
+ */
+export const WEBHOOK_DELIVERY_STATUSES = ['pending', 'delivered', 'failed'];
+//# sourceMappingURL=webhook-endpoint-binding.js.map

package/dist/webhook-endpoint-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-endpoint-binding.js","sourceRoot":"","sources":["../src/webhook-endpoint-binding.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAmEjC,gDAAgD;AAChD,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,cAAc,CAAU,CAAC;AAgI7D,mCAAmC;AAEnC;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAU,CAAC"}

package/dist/xml.d.ts

@@ -0,0 +1,79 @@
+/**
+ * S3-standard error body. `<Error><Code>...</Code><Message>...</Message>...</Error>`.
+ */
+export declare function errorXml(code: string, message: string, extra?: Readonly<Record<string, string>>): string;
+/**
+ * S3 `ListObjectsV2` result envelope. `contents` are the matched keys
+ * with metadata; `CommonPrefixes` is never emitted — delimiters are not
+ * supported.
+ */
+export interface ListBucketResultInput {
+    readonly bucket: string;
+    readonly prefix: string;
+    readonly maxKeys: number;
+    readonly isTruncated: boolean;
+    readonly continuationToken?: string;
+    readonly nextContinuationToken?: string;
+    readonly contents: ReadonlyArray<{
+        readonly key: string;
+        readonly lastModified: string;
+        readonly etag: string;
+        readonly size: number;
+    }>;
+}
+export declare function listBucketResultXml(input: ListBucketResultInput): string;
+/**
+ * S3 `InitiateMultipartUpload` result envelope.
+ */
+export interface InitiateMultipartUploadResultInput {
+    readonly bucket: string;
+    readonly key: string;
+    readonly uploadId: string;
+}
+export declare function initiateMultipartUploadResultXml(input: InitiateMultipartUploadResultInput): string;
+/**
+ * S3 `CompleteMultipartUpload` result envelope.
+ */
+export interface CompleteMultipartUploadResultInput {
+    readonly bucket: string;
+    readonly key: string;
+    readonly etag: string;
+    readonly location: string;
+}
+export declare function completeMultipartUploadResultXml(input: CompleteMultipartUploadResultInput): string;
+/**
+ * S3 `ListParts` result envelope.
+ */
+export interface ListPartsResultInput {
+    readonly bucket: string;
+    readonly key: string;
+    readonly uploadId: string;
+    readonly parts: ReadonlyArray<{
+        readonly partNumber: number;
+        readonly etag: string;
+        readonly size: number;
+        readonly lastModified: string;
+    }>;
+}
+export declare function listPartsResultXml(input: ListPartsResultInput): string;
+/**
+ * Parse the `CompleteMultipartUpload` request body:
+ *
+ *   <CompleteMultipartUpload>
+ *     <Part>
+ *       <PartNumber>1</PartNumber>
+ *       <ETag>"..."</ETag>
+ *     </Part>
+ *     ...
+ *   </CompleteMultipartUpload>
+ *
+ * Returns the declared parts in body order (S3 REQUIRES ascending
+ * PartNumber; the completer verifies before assembling). Hand-rolled
+ * regex — the shape is trivial and the input is machine-generated by
+ * AWS SDKs.
+ */
+export declare function parseCompleteMultipartUploadXml(body: string): {
+    partNumber: number;
+    etag: string;
+}[] | null;
+//# sourceMappingURL=xml.d.ts.map

package/dist/xml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml.d.ts","sourceRoot":"","sources":["../src/xml.ts"],"names":[],"mappings":"AAgBA;;GAEG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,GAC3C,MAAM,CAKR;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;QAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;KACvB,CAAC,CAAC;CACJ;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAsBxE;AAED;;GAEG;AACH,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,kCAAkC,GACxC,MAAM,CAOR;AAED;;GAEG;AACH,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,kCAAkC,GACxC,MAAM,CAQR;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;QAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;KAC/B,CAAC,CAAC;CACJ;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAQtE;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,MAAM,GACX;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,IAAI,CAe/C"}

package/dist/xml.js

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * Minimal hand-rolled XML serialization for the S3-compat wire
+ * surface. S3 response shapes are shallow (5 or so total across the
+ * surface); pulling in a full XML library would be overkill.
+ *
+ * Every serializer emits a single top-level element with the XML prolog
+ * and the S3-standard namespace (`http://s3.amazonaws.com/doc/2006-03-01/`).
+ * Escaping is applied to text content and attribute values.
+ */
+const XML_PROLOG = '<?xml version="1.0" encoding="UTF-8"?>';
+const S3_NS = 'http://s3.amazonaws.com/doc/2006-03-01/';
+/**
+ * S3-standard error body. `<Error><Code>...</Code><Message>...</Message>...</Error>`.
+ */
+export function errorXml(code, message, extra = {}) {
+    const extraTags = Object.entries(extra)
+        .map(([k, v]) => tag(k, v))
+        .join('');
+    return `${XML_PROLOG}<Error>${tag('Code', code)}${tag('Message', message)}${extraTags}</Error>`;
+}
+export function listBucketResultXml(input) {
+    const contents = input.contents
+        .map((c) => `<Contents>${tag('Key', c.key)}${tag('LastModified', c.lastModified)}${tag('ETag', quote(c.etag))}${tag('Size', String(c.size))}${tag('StorageClass', 'STANDARD')}</Contents>`)
+        .join('');
+    const parts = [
+        tag('Name', input.bucket),
+        tag('Prefix', input.prefix),
+        tag('KeyCount', String(input.contents.length)),
+        tag('MaxKeys', String(input.maxKeys)),
+        tag('IsTruncated', input.isTruncated ? 'true' : 'false'),
+        ...(input.continuationToken !== undefined
+            ? [tag('ContinuationToken', input.continuationToken)]
+            : []),
+        ...(input.nextContinuationToken !== undefined
+            ? [tag('NextContinuationToken', input.nextContinuationToken)]
+            : []),
+        contents,
+    ];
+    return `${XML_PROLOG}<ListBucketResult xmlns="${S3_NS}">${parts.join('')}</ListBucketResult>`;
+}
+export function initiateMultipartUploadResultXml(input) {
+    const parts = [
+        tag('Bucket', input.bucket),
+        tag('Key', input.key),
+        tag('UploadId', input.uploadId),
+    ];
+    return `${XML_PROLOG}<InitiateMultipartUploadResult xmlns="${S3_NS}">${parts.join('')}</InitiateMultipartUploadResult>`;
+}
+export function completeMultipartUploadResultXml(input) {
+    const parts = [
+        tag('Location', input.location),
+        tag('Bucket', input.bucket),
+        tag('Key', input.key),
+        tag('ETag', quote(input.etag)),
+    ];
+    return `${XML_PROLOG}<CompleteMultipartUploadResult xmlns="${S3_NS}">${parts.join('')}</CompleteMultipartUploadResult>`;
+}
+export function listPartsResultXml(input) {
+    const parts = input.parts
+        .map((p) => `<Part>${tag('PartNumber', String(p.partNumber))}${tag('LastModified', p.lastModified)}${tag('ETag', quote(p.etag))}${tag('Size', String(p.size))}</Part>`)
+        .join('');
+    return `${XML_PROLOG}<ListPartsResult xmlns="${S3_NS}">${tag('Bucket', input.bucket)}${tag('Key', input.key)}${tag('UploadId', input.uploadId)}${parts}</ListPartsResult>`;
+}
+// -------------------- parsing (CompleteMultipartUpload body) --------------------
+/**
+ * Parse the `CompleteMultipartUpload` request body:
+ *
+ *   <CompleteMultipartUpload>
+ *     <Part>
+ *       <PartNumber>1</PartNumber>
+ *       <ETag>"..."</ETag>
+ *     </Part>
+ *     ...
+ *   </CompleteMultipartUpload>
+ *
+ * Returns the declared parts in body order (S3 REQUIRES ascending
+ * PartNumber; the completer verifies before assembling). Hand-rolled
+ * regex — the shape is trivial and the input is machine-generated by
+ * AWS SDKs.
+ */
+export function parseCompleteMultipartUploadXml(body) {
+    const parts = [];
+    const partRe = /<Part>\s*(?:<PartNumber>(\d+)<\/PartNumber>\s*<ETag>([^<]+)<\/ETag>|<ETag>([^<]+)<\/ETag>\s*<PartNumber>(\d+)<\/PartNumber>)\s*<\/Part>/g;
+    let match = partRe.exec(body);
+    while (match !== null) {
+        const partNumber = Number.parseInt((match[1] ?? match[4]), 10);
+        const etagRaw = (match[2] ?? match[3]);
+        const etag = etagRaw.replace(/^"|"$/g, '');
+        if (!Number.isFinite(partNumber) || partNumber < 1)
+            return null;
+        parts.push({ partNumber, etag });
+        match = partRe.exec(body);
+    }
+    if (parts.length === 0)
+        return null;
+    return parts;
+}
+// -------------------- primitives --------------------
+function tag(name, value) {
+    return `<${name}>${escapeXml(value)}</${name}>`;
+}
+function quote(s) {
+    return s.startsWith('"') ? s : `"${s}"`;
+}
+// In XML text content, only `&` and `<` MUST be escaped (`>` is only
+// required inside `]]>`). `"` and `'` need escaping only in attribute
+// values. S3 responses don't use attribute values, so we escape the
+// minimum set — matching what real S3 emits (e.g. `<ETag>"abc"</ETag>`
+// with literal quotes).
+function escapeXml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;');
+}
+//# sourceMappingURL=xml.js.map

package/dist/xml.js.map

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