@xtandard/webhooks 0.1.0

package/dist/redis-CvLi0KF7.mjs

@@ -0,0 +1,254 @@
+import { t as __exportAll } from "./chunk-D7D4PA-g.mjs";
+import { T as parseDueKey, m as dueKey, p as deliveryKey } from "./keys-Byyj4quQ.mjs";
+import { a as requirePeer } from "./contract-BEhDcd_5.mjs";
+//#region src/storage/redis.ts
+var redis_exports = /* @__PURE__ */ __exportAll({
+	createRedisJSONStorage: () => createRedisJSONStorage,
+	createRedisStorage: () => createRedisStorage
+});
+/** Plain strings containing JSON — works on any Redis. */
+const stringCodec = {
+	async get(c, key) {
+		const raw = await c.get(key);
+		return raw === null ? null : JSON.parse(raw);
+	},
+	async set(c, key, value) {
+		await c.set(key, JSON.stringify(value));
+	}
+};
+/** Native RedisJSON documents — requires the JSON module on the server. */
+const jsonCodec = {
+	async get(c, key) {
+		return await requireJson(c).get(key) ?? null;
+	},
+	async set(c, key, value) {
+		await requireJson(c).set(key, "$", value);
+	}
+};
+function requireJson(c) {
+	if (!c.json) throw new Error("createRedisJSONStorage: the client exposes no `json` commands — use node-redis (the `redis` package) v4+, and a server with the RedisJSON module (Redis 8 / Redis Stack).");
+	return c.json;
+}
+/** Matches the due-index keys the adapter mirrors into the due sorted set. */
+const DUE_KEY_RE = new RegExp(`^whk/[^/]+/due/`);
+/**
+* Atomically pop up to `ARGV[2]` members due at or before `ARGV[1]` by
+* repositioning them at `ARGV[3]` (the lease expiry). Repositioning — instead of
+* removing — means a claimer that crashes right after this script re-surfaces
+* its members automatically when the lease expires.
+*/
+const CLAIM_SCRIPT = `
+local members = redis.call('ZRANGEBYSCORE', KEYS[1], 0, ARGV[1], 'LIMIT', 0, tonumber(ARGV[2]))
+for i = 1, #members do
+  redis.call('ZADD', KEYS[1], ARGV[3], members[i])
+end
+return members`;
+/**
+* Create a Redis-backed {@link RedisWebhooksStorage}. Connection is lazy: the
+* client is created/connected on the first storage operation and reused
+* thereafter, guarded by a single connection promise so concurrent calls connect
+* once.
+*
+* @example
+* ```ts
+* import { createRedisStorage } from "@xtandard/webhooks/storage/redis";
+*
+* const storage = createRedisStorage({
+*   url: process.env.REDIS_URL ?? "redis://localhost:6379",
+*   prefix: "myapp:webhooks",
+*   onError: (err) => console.error("[webhooks/redis]", err),
+* });
+*
+* // Disconnect when the process exits:
+* // process.on("SIGTERM", () => storage.close());
+* ```
+*/
+function createRedisStorage(options) {
+	return buildRedisStorage(options, stringCodec);
+}
+/**
+* Create a Redis-backed {@link RedisWebhooksStorage} that stores values as native
+* **RedisJSON** documents (`JSON.SET`/`JSON.GET`) instead of strings — making
+* the stored records queryable with JSONPath (`JSON.GET key $.status`) and
+* indexable with RediSearch, while the webhooks system behaves identically.
+*
+* Requires the JSON module on the server (built into Redis 8; Redis Stack; or
+* `redisjson` loaded). Same options and semantics as {@link createRedisStorage},
+* including lazy connection, `SCAN`-based `getKeys`, keyspace-notification
+* `watch`, and the native due-queue `claimDue`. **Do not point it at keys
+* written by `createRedisStorage`** (or vice versa) — the underlying types
+* differ and Redis answers `WRONGTYPE`.
+*
+* @example
+* ```ts
+* import { createRedisJSONStorage } from "@xtandard/webhooks/storage/redis";
+*
+* const storage = createRedisJSONStorage({
+*   url: process.env.REDIS_URL ?? "redis://localhost:6379",
+*   prefix: "myapp:webhooks",
+* });
+* // Then, in redis-cli: JSON.GET myapp:webhooks:whk/acme/deliveries/dlv_1 $.status
+* ```
+*/
+function createRedisJSONStorage(options) {
+	return buildRedisStorage(options, jsonCodec);
+}
+/** Shared implementation — connection, prefixing, SCAN, watch, due queue, close. */
+function buildRedisStorage(options, codec) {
+	const { url, prefix } = options;
+	const fullPrefix = prefix ? `${prefix}:` : "";
+	const ownsClient = !options.client;
+	let client = options.client;
+	let connecting;
+	const attachErrorHandler = (c) => {
+		c.on?.("error", (err) => options.onError?.(err));
+	};
+	if (client) attachErrorHandler(client);
+	/** Resolve a connected client, creating/connecting on first use. */
+	async function getClient() {
+		if (client?.isOpen) return client;
+		connecting ??= (async () => {
+			if (!client) {
+				let createClient;
+				try {
+					({createClient} = await import("redis"));
+				} catch {
+					requirePeer("redis", "storage/redis");
+				}
+				client = createClient({
+					url,
+					disableOfflineQueue: true,
+					socket: { reconnectStrategy: (retries) => Math.min(retries * 100, 3e3) }
+				});
+				attachErrorHandler(client);
+			}
+			if (!client.isOpen) await client.connect();
+			return client;
+		})();
+		try {
+			return await connecting;
+		} finally {
+			connecting = void 0;
+		}
+	}
+	/** Prepend the namespace to a caller key. */
+	const toRedisKey = (key) => `${fullPrefix}${key}`;
+	/** Strip the namespace off a Redis key, yielding the caller key. */
+	const fromRedisKey = (key) => fullPrefix && key.startsWith(fullPrefix) ? key.slice(fullPrefix.length) : key;
+	/**
+	* The due-index sorted set (members are caller due keys; the zset key itself
+	* carries the namespace). `:`-separated so it never collides with `whk/…`.
+	*/
+	const dueZsetKey = toRedisKey(`whk:due`);
+	return {
+		async getItem(key) {
+			const c = await getClient();
+			return await codec.get(c, toRedisKey(key)) ?? null;
+		},
+		async setItem(key, value) {
+			const c = await getClient();
+			await codec.set(c, toRedisKey(key), value);
+			if (DUE_KEY_RE.test(key)) {
+				const parsed = parseDueKey(key);
+				if (parsed) await c.zAdd(dueZsetKey, {
+					score: parsed.dueAtMillis,
+					value: key
+				});
+			}
+		},
+		async removeItem(key) {
+			const c = await getClient();
+			await c.del(toRedisKey(key));
+			if (DUE_KEY_RE.test(key)) await c.zRem(dueZsetKey, key);
+		},
+		async getKeys(prefix) {
+			const c = await getClient();
+			const match = `${toRedisKey(prefix)}*`;
+			const out = [];
+			for await (const entry of c.scanIterator({
+				MATCH: match,
+				COUNT: 100
+			})) if (Array.isArray(entry)) for (const k of entry) out.push(fromRedisKey(k));
+			else out.push(fromRedisKey(entry));
+			return out;
+		},
+		async claimDue(input) {
+			const c = await getClient();
+			const nowMillis = Date.parse(input.now);
+			const leaseExpiryMillis = nowMillis + input.leaseMs;
+			const members = await c.eval(CLAIM_SCRIPT, {
+				keys: [dueZsetKey],
+				arguments: [
+					String(nowMillis),
+					String(input.limit),
+					String(leaseExpiryMillis)
+				]
+			});
+			const claimed = [];
+			for (const member of members ?? []) {
+				if (!parseDueKey(member)) {
+					await c.zRem(dueZsetKey, member);
+					continue;
+				}
+				const entry = await codec.get(c, toRedisKey(member));
+				if (!entry) {
+					await c.zRem(dueZsetKey, member);
+					continue;
+				}
+				const dKey = deliveryKey(entry.app, entry.deliveryId);
+				const delivery = await codec.get(c, toRedisKey(dKey));
+				if (!delivery || delivery.status === "succeeded" || delivery.status === "failed") {
+					await c.del(toRedisKey(member));
+					await c.zRem(dueZsetKey, member);
+					continue;
+				}
+				const leaseExpired = delivery.status === "delivering" && (!delivery.leaseUntil || Date.parse(delivery.leaseUntil) <= nowMillis);
+				if (delivery.status !== "pending" && !leaseExpired) continue;
+				const leaseUntil = new Date(leaseExpiryMillis).toISOString();
+				const next = {
+					...delivery,
+					status: "delivering",
+					leaseUntil,
+					updatedAt: input.now
+				};
+				await codec.set(c, toRedisKey(dKey), next);
+				const nextDueKey = dueKey(entry.app, leaseExpiryMillis, entry.deliveryId);
+				await c.del(toRedisKey(member));
+				await c.zRem(dueZsetKey, member);
+				await codec.set(c, toRedisKey(nextDueKey), entry);
+				await c.zAdd(dueZsetKey, {
+					score: leaseExpiryMillis,
+					value: nextDueKey
+				});
+				claimed.push(next);
+			}
+			return claimed;
+		},
+		async watch(prefix, callback) {
+			const subscriber = (await getClient()).duplicate();
+			attachErrorHandler(subscriber);
+			await subscriber.connect();
+			const pattern = `__keyspace@*__:${toRedisKey(prefix)}*`;
+			await subscriber.pSubscribe(pattern, (event, channel) => {
+				const idx = channel.indexOf("__:");
+				if (idx === -1) return;
+				const key = fromRedisKey(channel.slice(idx + 3));
+				if (!key.startsWith(prefix)) return;
+				callback({
+					type: event === "del" || event === "expired" ? "remove" : "update",
+					key
+				});
+			});
+			return () => {
+				subscriber.disconnect();
+			};
+		},
+		async close() {
+			if (ownsClient && client?.isOpen) await client.quit();
+		}
+	};
+}
+//#endregion
+export { createRedisStorage as n, redis_exports as r, createRedisJSONStorage as t };
+
+//# sourceMappingURL=redis-CvLi0KF7.mjs.map

package/dist/redis-CvLi0KF7.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-CvLi0KF7.mjs","names":[],"sources":["../src/storage/redis.ts"],"sourcesContent":["/**\n * Redis storage adapters built on the [`redis`](https://github.com/redis/node-redis)\n * package (node-redis v4/v5), an optional peer dependency. You can either pass a\n * pre-connected `client` or a `url` to connect lazily on first use. An optional\n * `prefix` is prepended (with a `:` separator) to every key so multiple\n * deployments can share a Redis instance without collisions; the prefix is\n * stripped from keys returned by {@link RedisWebhooksStorage.getKeys}.\n *\n * Two variants over the same plumbing, differing only in the value encoding:\n *\n * - {@link createRedisStorage} — values are plain **strings** containing JSON\n *   (`SET`/`GET`). Works on any Redis; the default choice.\n * - {@link createRedisJSONStorage} — values are native **RedisJSON** documents\n *   (`JSON.SET`/`JSON.GET`), so the stored data is queryable with JSONPath and\n *   indexable with RediSearch. Requires the JSON module (Redis 8 / Redis Stack).\n *   Do NOT point both variants at the same keys — the types are incompatible\n *   (`WRONGTYPE`).\n *\n * `getKeys` uses a non-blocking `SCAN` cursor (never the blocking `KEYS`\n * command). `watch` is implemented with Redis keyspace notifications; it\n * requires the server to be configured with `notify-keyspace-events` covering\n * generic + string + expiry events (e.g. `KEA` — whose `A` class also covers the\n * module events that RedisJSON writes emit, e.g. `json.set`).\n *\n * ## Native delivery queue (`claimDue`)\n *\n * Both variants implement {@link DeliveryQueueStorage} natively: a sorted set at\n * `<prefix>whk:due` (score = due-time millis, member = the `whk/{app}/due/…`\n * key) is maintained alongside every `setItem`/`removeItem` that touches a\n * due-index key, keeping the zset and the plain keys consistent (so the generic\n * scan path still works). `claimDue` runs a small Lua script that atomically\n * pops due members up to `limit` by **repositioning** them at the lease expiry —\n * exclusivity between concurrent claimers is guaranteed by the script, and a\n * crashed claimer's members re-surface when the lease expires. The per-delivery\n * claim (verify claimable, write the lease, move the due key) then happens in\n * JS; under a race a claimer may return fewer than `limit`, never a duplicate.\n *\n * @module\n */\n\nimport type { RedisClientType } from \"redis\";\nimport { deliveryKey, dueKey, parseDueKey, ROOT, type DueEntry } from \"../keys.ts\";\nimport type { Delivery } from \"../schema.ts\";\nimport { requirePeer } from \"./contract.ts\";\nimport type {\n  DeliveryQueueStorage,\n  StorageChangeEvent,\n  WatchableWebhooksStorage,\n} from \"./contract.ts\";\n\n/** Options for {@link createRedisStorage}. */\nexport interface RedisStorageOptions {\n  /** Connection URL (e.g. `redis://localhost:6379`). Used when no `client` is given. */\n  url?: string;\n  /** A pre-constructed (optionally pre-connected) node-redis client. */\n  client?: RedisClientType;\n  /** Optional key namespace prepended to every key, joined with `:`. */\n  prefix?: string;\n  /**\n   * Called on client `error` events (connection drops, reconnect failures).\n   * A handler is always attached internally so a downed Redis never crashes the\n   * process via an unhandled `error` event — this just lets you observe/log them.\n   */\n  onError?: (error: unknown) => void;\n}\n\n/**\n * A {@link WatchableWebhooksStorage} + {@link DeliveryQueueStorage} backed by\n * Redis, plus a `close()` method that disconnects the client — but only the one\n * this adapter created. A client you passed in is left for you to manage.\n */\nexport interface RedisWebhooksStorage extends WatchableWebhooksStorage, DeliveryQueueStorage {\n  /** Disconnect the underlying client if this adapter created it. No-op otherwise. */\n  close(): Promise<void>;\n}\n\n/** Minimal structural view of the node-redis client surface this adapter uses. */\ninterface RedisLike {\n  isOpen?: boolean;\n  on?(event: string, listener: (...args: unknown[]) => void): unknown;\n  connect(): Promise<unknown>;\n  quit(): Promise<unknown>;\n  get(key: string): Promise<string | null>;\n  set(key: string, value: string): Promise<unknown>;\n  del(key: string): Promise<unknown>;\n  zAdd(key: string, members: { score: number; value: string }): Promise<unknown>;\n  zRem(key: string, member: string): Promise<unknown>;\n  eval(script: string, options?: { keys?: string[]; arguments?: string[] }): Promise<unknown>;\n  /** RedisJSON module commands (bundled in node-redis; the SERVER needs the module). */\n  json?: {\n    get(key: string): Promise<unknown>;\n    set(key: string, path: string, value: unknown): Promise<unknown>;\n  };\n  scanIterator(options?: { MATCH?: string; COUNT?: number }): AsyncIterable<string | string[]>;\n  duplicate(): RedisLike;\n  pSubscribe(\n    pattern: string,\n    listener: (message: string, channel: string) => void,\n  ): Promise<unknown>;\n  disconnect(): Promise<unknown>;\n}\n\n/** How a variant reads/writes values (the only place the two adapters differ). */\ninterface RedisValueCodec {\n  get(c: RedisLike, key: string): Promise<unknown>;\n  set(c: RedisLike, key: string, value: unknown): Promise<void>;\n}\n\n/** Plain strings containing JSON — works on any Redis. */\nconst stringCodec: RedisValueCodec = {\n  async get(c, key) {\n    const raw = await c.get(key);\n    return raw === null ? null : (JSON.parse(raw) as unknown);\n  },\n  async set(c, key, value) {\n    await c.set(key, JSON.stringify(value));\n  },\n};\n\n/** Native RedisJSON documents — requires the JSON module on the server. */\nconst jsonCodec: RedisValueCodec = {\n  async get(c, key) {\n    const value = await requireJson(c).get(key);\n    return value ?? null;\n  },\n  async set(c, key, value) {\n    await requireJson(c).set(key, \"$\", value);\n  },\n};\n\nfunction requireJson(c: RedisLike): NonNullable<RedisLike[\"json\"]> {\n  if (!c.json) {\n    throw new Error(\n      \"createRedisJSONStorage: the client exposes no `json` commands — use node-redis \" +\n        \"(the `redis` package) v4+, and a server with the RedisJSON module (Redis 8 / Redis Stack).\",\n    );\n  }\n  return c.json;\n}\n\n/** Matches the due-index keys the adapter mirrors into the due sorted set. */\nconst DUE_KEY_RE = new RegExp(`^${ROOT}/[^/]+/due/`);\n\n/**\n * Atomically pop up to `ARGV[2]` members due at or before `ARGV[1]` by\n * repositioning them at `ARGV[3]` (the lease expiry). Repositioning — instead of\n * removing — means a claimer that crashes right after this script re-surfaces\n * its members automatically when the lease expires.\n */\nconst CLAIM_SCRIPT = `\nlocal members = redis.call('ZRANGEBYSCORE', KEYS[1], 0, ARGV[1], 'LIMIT', 0, tonumber(ARGV[2]))\nfor i = 1, #members do\n  redis.call('ZADD', KEYS[1], ARGV[3], members[i])\nend\nreturn members`;\n\n/**\n * Create a Redis-backed {@link RedisWebhooksStorage}. Connection is lazy: the\n * client is created/connected on the first storage operation and reused\n * thereafter, guarded by a single connection promise so concurrent calls connect\n * once.\n *\n * @example\n * ```ts\n * import { createRedisStorage } from \"@xtandard/webhooks/storage/redis\";\n *\n * const storage = createRedisStorage({\n *   url: process.env.REDIS_URL ?? \"redis://localhost:6379\",\n *   prefix: \"myapp:webhooks\",\n *   onError: (err) => console.error(\"[webhooks/redis]\", err),\n * });\n *\n * // Disconnect when the process exits:\n * // process.on(\"SIGTERM\", () => storage.close());\n * ```\n */\nexport function createRedisStorage(options: RedisStorageOptions): RedisWebhooksStorage {\n  return buildRedisStorage(options, stringCodec);\n}\n\n/**\n * Create a Redis-backed {@link RedisWebhooksStorage} that stores values as native\n * **RedisJSON** documents (`JSON.SET`/`JSON.GET`) instead of strings — making\n * the stored records queryable with JSONPath (`JSON.GET key $.status`) and\n * indexable with RediSearch, while the webhooks system behaves identically.\n *\n * Requires the JSON module on the server (built into Redis 8; Redis Stack; or\n * `redisjson` loaded). Same options and semantics as {@link createRedisStorage},\n * including lazy connection, `SCAN`-based `getKeys`, keyspace-notification\n * `watch`, and the native due-queue `claimDue`. **Do not point it at keys\n * written by `createRedisStorage`** (or vice versa) — the underlying types\n * differ and Redis answers `WRONGTYPE`.\n *\n * @example\n * ```ts\n * import { createRedisJSONStorage } from \"@xtandard/webhooks/storage/redis\";\n *\n * const storage = createRedisJSONStorage({\n *   url: process.env.REDIS_URL ?? \"redis://localhost:6379\",\n *   prefix: \"myapp:webhooks\",\n * });\n * // Then, in redis-cli: JSON.GET myapp:webhooks:whk/acme/deliveries/dlv_1 $.status\n * ```\n */\nexport function createRedisJSONStorage(options: RedisStorageOptions): RedisWebhooksStorage {\n  return buildRedisStorage(options, jsonCodec);\n}\n\n/** Shared implementation — connection, prefixing, SCAN, watch, due queue, close. */\nfunction buildRedisStorage(\n  options: RedisStorageOptions,\n  codec: RedisValueCodec,\n): RedisWebhooksStorage {\n  const { url, prefix } = options;\n  const fullPrefix = prefix ? `${prefix}:` : \"\";\n  const ownsClient = !options.client;\n\n  let client: RedisLike | undefined = options.client as RedisLike | undefined;\n  let connecting: Promise<RedisLike> | undefined;\n\n  // node-redis emits `error` on connection drops and reconnect attempts. Without a\n  // listener Node treats it as an unhandled error and crashes the process — which\n  // would defeat the whole \"storage can be down\" promise. Always attach one.\n  const attachErrorHandler = (c: RedisLike): void => {\n    c.on?.(\"error\", (err: unknown) => options.onError?.(err));\n  };\n  if (client) attachErrorHandler(client);\n\n  /** Resolve a connected client, creating/connecting on first use. */\n  async function getClient(): Promise<RedisLike> {\n    if (client?.isOpen) return client;\n    connecting ??= (async () => {\n      if (!client) {\n        let createClient: (opts: Record<string, unknown>) => RedisLike;\n        try {\n          ({ createClient } = (await import(\"redis\")) as unknown as {\n            createClient: (opts: Record<string, unknown>) => RedisLike;\n          });\n        } catch {\n          requirePeer(\"redis\", \"storage/redis\");\n        }\n        // disableOfflineQueue: commands reject immediately when the socket is down\n        // (instead of queueing forever) so a dispatcher tick fails fast and the\n        // next tick retries. The reconnect strategy keeps trying with a capped\n        // backoff so it recovers automatically.\n        client = createClient({\n          url,\n          disableOfflineQueue: true,\n          socket: { reconnectStrategy: (retries: number) => Math.min(retries * 100, 3000) },\n        });\n        attachErrorHandler(client);\n      }\n      if (!client.isOpen) await client.connect();\n      return client;\n    })();\n    try {\n      return await connecting;\n    } finally {\n      connecting = undefined;\n    }\n  }\n\n  /** Prepend the namespace to a caller key. */\n  const toRedisKey = (key: string): string => `${fullPrefix}${key}`;\n  /** Strip the namespace off a Redis key, yielding the caller key. */\n  const fromRedisKey = (key: string): string =>\n    fullPrefix && key.startsWith(fullPrefix) ? key.slice(fullPrefix.length) : key;\n\n  /**\n   * The due-index sorted set (members are caller due keys; the zset key itself\n   * carries the namespace). `:`-separated so it never collides with `whk/…`.\n   */\n  const dueZsetKey = toRedisKey(`${ROOT}:due`);\n\n  return {\n    async getItem<T>(key: string): Promise<T | null> {\n      const c = await getClient();\n      return ((await codec.get(c, toRedisKey(key))) as T | null) ?? null;\n    },\n\n    async setItem<T>(key: string, value: T): Promise<void> {\n      const c = await getClient();\n      await codec.set(c, toRedisKey(key), value);\n      // Mirror due-index keys into the due zset so claimDue can pop by score.\n      if (DUE_KEY_RE.test(key)) {\n        const parsed = parseDueKey(key);\n        if (parsed) await c.zAdd(dueZsetKey, { score: parsed.dueAtMillis, value: key });\n      }\n    },\n\n    async removeItem(key: string): Promise<void> {\n      const c = await getClient();\n      await c.del(toRedisKey(key));\n      if (DUE_KEY_RE.test(key)) await c.zRem(dueZsetKey, key);\n    },\n\n    async getKeys(prefix: string): Promise<string[]> {\n      const c = await getClient();\n      const match = `${toRedisKey(prefix)}*`;\n      const out: string[] = [];\n      for await (const entry of c.scanIterator({ MATCH: match, COUNT: 100 })) {\n        // node-redis v4 yields one key per iteration; v5 may yield batches.\n        if (Array.isArray(entry)) {\n          for (const k of entry) out.push(fromRedisKey(k));\n        } else {\n          out.push(fromRedisKey(entry));\n        }\n      }\n      return out;\n    },\n\n    async claimDue(input: { now: string; limit: number; leaseMs: number }): Promise<Delivery[]> {\n      const c = await getClient();\n      const nowMillis = Date.parse(input.now);\n      const leaseExpiryMillis = nowMillis + input.leaseMs;\n      // Atomic pop: reposition due members at the lease expiry so no concurrent\n      // claimer can see them, while a crashed claimer's members re-surface.\n      const members = (await c.eval(CLAIM_SCRIPT, {\n        keys: [dueZsetKey],\n        arguments: [String(nowMillis), String(input.limit), String(leaseExpiryMillis)],\n      })) as string[] | null;\n\n      const claimed: Delivery[] = [];\n      for (const member of members ?? []) {\n        const parsed = parseDueKey(member);\n        if (!parsed) {\n          await c.zRem(dueZsetKey, member); // unparseable member — sweep from the zset\n          continue;\n        }\n        const entry = (await codec.get(c, toRedisKey(member))) as DueEntry | null;\n        if (!entry) {\n          await c.zRem(dueZsetKey, member); // stale zset member with no backing key\n          continue;\n        }\n        const dKey = deliveryKey(entry.app, entry.deliveryId);\n        const delivery = (await codec.get(c, toRedisKey(dKey))) as Delivery | null;\n        // Orphaned or already-terminal entries are garbage — sweep them.\n        if (!delivery || delivery.status === \"succeeded\" || delivery.status === \"failed\") {\n          await c.del(toRedisKey(member));\n          await c.zRem(dueZsetKey, member);\n          continue;\n        }\n        // Claimable = pending, or delivering with an expired lease. A delivery\n        // with an active lease was claimed elsewhere; its member is already\n        // repositioned near the lease expiry, so just skip it.\n        const leaseExpired =\n          delivery.status === \"delivering\" &&\n          (!delivery.leaseUntil || Date.parse(delivery.leaseUntil) <= nowMillis);\n        if (delivery.status !== \"pending\" && !leaseExpired) continue;\n\n        const leaseUntil = new Date(leaseExpiryMillis).toISOString();\n        const next: Delivery = {\n          ...delivery,\n          status: \"delivering\",\n          leaseUntil,\n          updatedAt: input.now,\n        };\n        await codec.set(c, toRedisKey(dKey), next);\n        // Move the due entry (plain key + zset member) to the lease-expiry\n        // position so a crashed claimer's work re-surfaces automatically.\n        const nextDueKey = dueKey(entry.app, leaseExpiryMillis, entry.deliveryId);\n        await c.del(toRedisKey(member));\n        await c.zRem(dueZsetKey, member);\n        await codec.set(c, toRedisKey(nextDueKey), entry);\n        await c.zAdd(dueZsetKey, { score: leaseExpiryMillis, value: nextDueKey });\n        claimed.push(next);\n      }\n      return claimed;\n    },\n\n    async watch(\n      prefix: string,\n      callback: (event: StorageChangeEvent) => void,\n    ): Promise<() => void> {\n      // Keyspace notifications publish to `__keyspace@<db>__:<key>`; subscribe to\n      // all key events under our namespaced prefix and translate them.\n      const c = await getClient();\n      const subscriber = c.duplicate();\n      attachErrorHandler(subscriber);\n      await subscriber.connect();\n      const pattern = `__keyspace@*__:${toRedisKey(prefix)}*`;\n      await subscriber.pSubscribe(pattern, (event: string, channel: string) => {\n        const idx = channel.indexOf(\"__:\");\n        if (idx === -1) return;\n        const redisKey = channel.slice(idx + 3);\n        const key = fromRedisKey(redisKey);\n        if (!key.startsWith(prefix)) return;\n        const type: StorageChangeEvent[\"type\"] =\n          event === \"del\" || event === \"expired\" ? \"remove\" : \"update\";\n        callback({ type, key });\n      });\n      return () => {\n        void subscriber.disconnect();\n      };\n    },\n\n    async close(): Promise<void> {\n      if (ownsClient && client?.isOpen) await client.quit();\n    },\n  } satisfies RedisWebhooksStorage;\n}\n"],"mappings":"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"}

package/dist/roles-D0G9XqBq.cjs

@@ -0,0 +1,128 @@
+const require_keys = require("./keys-FiKpaVHX.cjs");
+const require_contract = require("./contract-B2d5dNU3.cjs");
+//#region src/authorization/roles.ts
+var roles_exports = /* @__PURE__ */ require_keys.__exportAll({
+	ALL_ACTIONS: () => ALL_ACTIONS,
+	DEFAULT_ROLE_POLICY: () => DEFAULT_ROLE_POLICY,
+	READ_ACTIONS: () => READ_ACTIONS,
+	rolesAuthorization: () => rolesAuthorization
+});
+/** Every action in the system, used to expand non-wildcard "all actions" presets. */
+const ALL_ACTIONS = [
+	"application:read",
+	"application:create",
+	"application:update",
+	"application:delete",
+	"event-type:read",
+	"event-type:create",
+	"event-type:update",
+	"event-type:delete",
+	"endpoint:read",
+	"endpoint:create",
+	"endpoint:update",
+	"endpoint:delete",
+	"endpoint:rotate-secret",
+	"endpoint:read-secret",
+	"message:read",
+	"message:publish",
+	"delivery:read",
+	"delivery:retry",
+	"audit:read"
+];
+/**
+* Every read-only action (the `*:read` subset of {@link ALL_ACTIONS}).
+* `endpoint:read-secret` is deliberately excluded — secret access is sensitive
+* and must be granted explicitly.
+*/
+const READ_ACTIONS = ALL_ACTIONS.filter((a) => a.endsWith(":read"));
+/**
+* The default role policy applied when {@link RolesAuthorizationOptions.policy}
+* is omitted.
+*
+* - `admin` — `"*"`, every action.
+* - `editor` — every action (explicit list, equivalent to `admin` here).
+* - `viewer` — every `*:read` action only.
+*/
+const DEFAULT_ROLE_POLICY = {
+	admin: "*",
+	editor: [...ALL_ACTIONS],
+	viewer: [...READ_ACTIONS]
+};
+/**
+* Create a role-based {@link AuthorizationProvider}.
+*
+* Decision order:
+* 1. If `readonly` and the action mutates → **deny**.
+* 2. If the principal is `null` → **deny**.
+* 3. If any of the principal's roles grants the action (via `"*"` or an explicit
+*    list) → **allow**; otherwise **deny**.
+*
+* @example
+* ```ts
+* import { rolesAuthorization } from "@xtandard/webhooks/authorization/roles";
+*
+* // Built-in admin/editor/viewer policy:
+* const authz = rolesAuthorization();
+*
+* // Custom policy:
+* const custom = rolesAuthorization({
+*   policy: {
+*     ops: ["delivery:read", "delivery:retry", "endpoint:read"],
+*     auditor: ["audit:read"],
+*   },
+* });
+* ```
+*/
+function rolesAuthorization(options = {}) {
+	const policy = options.policy ?? DEFAULT_ROLE_POLICY;
+	const readonly = options.readonly ?? false;
+	const grants = /* @__PURE__ */ new Map();
+	for (const [role, actions] of Object.entries(policy)) grants.set(role, actions === "*" ? null : new Set(actions));
+	return { async authorize(input) {
+		if (readonly && require_contract.isMutatingAction(input.action)) return false;
+		const principal = input.principal;
+		if (!principal) return false;
+		const roles = principal.roles;
+		if (!roles || roles.length === 0) return false;
+		for (const role of roles) {
+			if (!grants.has(role)) continue;
+			const granted = grants.get(role);
+			if (granted === null) return true;
+			if (granted?.has(input.action)) return true;
+		}
+		return false;
+	} };
+}
+//#endregion
+Object.defineProperty(exports, "ALL_ACTIONS", {
+	enumerable: true,
+	get: function() {
+		return ALL_ACTIONS;
+	}
+});
+Object.defineProperty(exports, "DEFAULT_ROLE_POLICY", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_ROLE_POLICY;
+	}
+});
+Object.defineProperty(exports, "READ_ACTIONS", {
+	enumerable: true,
+	get: function() {
+		return READ_ACTIONS;
+	}
+});
+Object.defineProperty(exports, "rolesAuthorization", {
+	enumerable: true,
+	get: function() {
+		return rolesAuthorization;
+	}
+});
+Object.defineProperty(exports, "roles_exports", {
+	enumerable: true,
+	get: function() {
+		return roles_exports;
+	}
+});
+
+//# sourceMappingURL=roles-D0G9XqBq.cjs.map

package/dist/roles-D0G9XqBq.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles-D0G9XqBq.cjs","names":["isMutatingAction"],"sources":["../src/authorization/roles.ts"],"sourcesContent":["/**\n * Role-based {@link AuthorizationProvider}. Maps each role name to the set of\n * {@link WebhooksAction}s it grants, then allows an action when *any* of the\n * principal's roles grants it.\n *\n * The policy is a flat `Record<roleName, WebhooksAction[] | \"*\">` — `\"*\"` is a\n * wildcard granting every action. When no `policy` is supplied, the built-in\n * {@link DEFAULT_ROLE_POLICY} applies (`admin`/`editor`/`viewer`).\n *\n * A `readonly` switch denies every {@link isMutatingAction mutating} action\n * regardless of role — handy for read-only mirrors or \"break glass\" lockdowns.\n *\n * @module\n */\n\nimport type { AuthorizationProvider, AuthorizeInput, WebhooksAction } from \"./contract.ts\";\nimport { isMutatingAction } from \"./contract.ts\";\n\n/** Every action in the system, used to expand non-wildcard \"all actions\" presets. */\nexport const ALL_ACTIONS: readonly WebhooksAction[] = [\n  \"application:read\",\n  \"application:create\",\n  \"application:update\",\n  \"application:delete\",\n  \"event-type:read\",\n  \"event-type:create\",\n  \"event-type:update\",\n  \"event-type:delete\",\n  \"endpoint:read\",\n  \"endpoint:create\",\n  \"endpoint:update\",\n  \"endpoint:delete\",\n  \"endpoint:rotate-secret\",\n  \"endpoint:read-secret\",\n  \"message:read\",\n  \"message:publish\",\n  \"delivery:read\",\n  \"delivery:retry\",\n  \"audit:read\",\n];\n\n/**\n * Every read-only action (the `*:read` subset of {@link ALL_ACTIONS}).\n * `endpoint:read-secret` is deliberately excluded — secret access is sensitive\n * and must be granted explicitly.\n */\nexport const READ_ACTIONS: readonly WebhooksAction[] = ALL_ACTIONS.filter((a) =>\n  a.endsWith(\":read\"),\n);\n\n/** A role policy: each role maps to an explicit action list or the `\"*\"` wildcard. */\nexport type RolePolicy = Record<string, WebhooksAction[] | \"*\">;\n\n/**\n * The default role policy applied when {@link RolesAuthorizationOptions.policy}\n * is omitted.\n *\n * - `admin` — `\"*\"`, every action.\n * - `editor` — every action (explicit list, equivalent to `admin` here).\n * - `viewer` — every `*:read` action only.\n */\nexport const DEFAULT_ROLE_POLICY: RolePolicy = {\n  admin: \"*\",\n  editor: [...ALL_ACTIONS],\n  viewer: [...READ_ACTIONS],\n};\n\n/** Options for {@link rolesAuthorization}. */\nexport interface RolesAuthorizationOptions {\n  /**\n   * Role → granted actions. `\"*\"` grants everything. Defaults to\n   * {@link DEFAULT_ROLE_POLICY} when omitted.\n   */\n  policy?: RolePolicy;\n  /**\n   * When `true`, every {@link isMutatingAction mutating} action is denied\n   * regardless of the principal's roles.\n   * @default false\n   */\n  readonly?: boolean;\n}\n\n/**\n * Create a role-based {@link AuthorizationProvider}.\n *\n * Decision order:\n * 1. If `readonly` and the action mutates → **deny**.\n * 2. If the principal is `null` → **deny**.\n * 3. If any of the principal's roles grants the action (via `\"*\"` or an explicit\n *    list) → **allow**; otherwise **deny**.\n *\n * @example\n * ```ts\n * import { rolesAuthorization } from \"@xtandard/webhooks/authorization/roles\";\n *\n * // Built-in admin/editor/viewer policy:\n * const authz = rolesAuthorization();\n *\n * // Custom policy:\n * const custom = rolesAuthorization({\n *   policy: {\n *     ops: [\"delivery:read\", \"delivery:retry\", \"endpoint:read\"],\n *     auditor: [\"audit:read\"],\n *   },\n * });\n * ```\n */\nexport function rolesAuthorization(options: RolesAuthorizationOptions = {}): AuthorizationProvider {\n  const policy = options.policy ?? DEFAULT_ROLE_POLICY;\n  const readonly = options.readonly ?? false;\n\n  // Pre-compute each role's granted action set for O(1) lookups. A role mapped\n  // to \"*\" is recorded as `null` (wildcard).\n  const grants = new Map<string, Set<WebhooksAction> | null>();\n  for (const [role, actions] of Object.entries(policy)) {\n    grants.set(role, actions === \"*\" ? null : new Set(actions));\n  }\n\n  return {\n    async authorize(input: AuthorizeInput): Promise<boolean> {\n      if (readonly && isMutatingAction(input.action)) return false;\n\n      const principal = input.principal;\n      if (!principal) return false;\n\n      const roles = principal.roles;\n      if (!roles || roles.length === 0) return false;\n\n      for (const role of roles) {\n        if (!grants.has(role)) continue;\n        const granted = grants.get(role);\n        if (granted === null) return true; // wildcard\n        if (granted?.has(input.action)) return true;\n      }\n      return false;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;AAmBA,MAAa,cAAyC;CACpD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;;;;;AAOA,MAAa,eAA0C,YAAY,QAAQ,MACzE,EAAE,SAAS,OAAO,CACpB;;;;;;;;;AAaA,MAAa,sBAAkC;CAC7C,OAAO;CACP,QAAQ,CAAC,GAAG,WAAW;CACvB,QAAQ,CAAC,GAAG,YAAY;AAC1B;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,SAAgB,mBAAmB,UAAqC,CAAC,GAA0B;CACjG,MAAM,SAAS,QAAQ,UAAU;CACjC,MAAM,WAAW,QAAQ,YAAY;CAIrC,MAAM,yBAAS,IAAI,IAAwC;CAC3D,KAAK,MAAM,CAAC,MAAM,YAAY,OAAO,QAAQ,MAAM,GACjD,OAAO,IAAI,MAAM,YAAY,MAAM,OAAO,IAAI,IAAI,OAAO,CAAC;CAG5D,OAAO,EACL,MAAM,UAAU,OAAyC;EACvD,IAAI,YAAYA,iBAAAA,iBAAiB,MAAM,MAAM,GAAG,OAAO;EAEvD,MAAM,YAAY,MAAM;EACxB,IAAI,CAAC,WAAW,OAAO;EAEvB,MAAM,QAAQ,UAAU;EACxB,IAAI,CAAC,SAAS,MAAM,WAAW,GAAG,OAAO;EAEzC,KAAK,MAAM,QAAQ,OAAO;GACxB,IAAI,CAAC,OAAO,IAAI,IAAI,GAAG;GACvB,MAAM,UAAU,OAAO,IAAI,IAAI;GAC/B,IAAI,YAAY,MAAM,OAAO;GAC7B,IAAI,SAAS,IAAI,MAAM,MAAM,GAAG,OAAO;EACzC;EACA,OAAO;CACT,EACF;AACF"}

package/dist/roles-vp361lTk.mjs

@@ -0,0 +1,99 @@
+import { t as __exportAll } from "./chunk-D7D4PA-g.mjs";
+import { n as isMutatingAction } from "./contract-9XpcwcCn.mjs";
+//#region src/authorization/roles.ts
+var roles_exports = /* @__PURE__ */ __exportAll({
+	ALL_ACTIONS: () => ALL_ACTIONS,
+	DEFAULT_ROLE_POLICY: () => DEFAULT_ROLE_POLICY,
+	READ_ACTIONS: () => READ_ACTIONS,
+	rolesAuthorization: () => rolesAuthorization
+});
+/** Every action in the system, used to expand non-wildcard "all actions" presets. */
+const ALL_ACTIONS = [
+	"application:read",
+	"application:create",
+	"application:update",
+	"application:delete",
+	"event-type:read",
+	"event-type:create",
+	"event-type:update",
+	"event-type:delete",
+	"endpoint:read",
+	"endpoint:create",
+	"endpoint:update",
+	"endpoint:delete",
+	"endpoint:rotate-secret",
+	"endpoint:read-secret",
+	"message:read",
+	"message:publish",
+	"delivery:read",
+	"delivery:retry",
+	"audit:read"
+];
+/**
+* Every read-only action (the `*:read` subset of {@link ALL_ACTIONS}).
+* `endpoint:read-secret` is deliberately excluded — secret access is sensitive
+* and must be granted explicitly.
+*/
+const READ_ACTIONS = ALL_ACTIONS.filter((a) => a.endsWith(":read"));
+/**
+* The default role policy applied when {@link RolesAuthorizationOptions.policy}
+* is omitted.
+*
+* - `admin` — `"*"`, every action.
+* - `editor` — every action (explicit list, equivalent to `admin` here).
+* - `viewer` — every `*:read` action only.
+*/
+const DEFAULT_ROLE_POLICY = {
+	admin: "*",
+	editor: [...ALL_ACTIONS],
+	viewer: [...READ_ACTIONS]
+};
+/**
+* Create a role-based {@link AuthorizationProvider}.
+*
+* Decision order:
+* 1. If `readonly` and the action mutates → **deny**.
+* 2. If the principal is `null` → **deny**.
+* 3. If any of the principal's roles grants the action (via `"*"` or an explicit
+*    list) → **allow**; otherwise **deny**.
+*
+* @example
+* ```ts
+* import { rolesAuthorization } from "@xtandard/webhooks/authorization/roles";
+*
+* // Built-in admin/editor/viewer policy:
+* const authz = rolesAuthorization();
+*
+* // Custom policy:
+* const custom = rolesAuthorization({
+*   policy: {
+*     ops: ["delivery:read", "delivery:retry", "endpoint:read"],
+*     auditor: ["audit:read"],
+*   },
+* });
+* ```
+*/
+function rolesAuthorization(options = {}) {
+	const policy = options.policy ?? DEFAULT_ROLE_POLICY;
+	const readonly = options.readonly ?? false;
+	const grants = /* @__PURE__ */ new Map();
+	for (const [role, actions] of Object.entries(policy)) grants.set(role, actions === "*" ? null : new Set(actions));
+	return { async authorize(input) {
+		if (readonly && isMutatingAction(input.action)) return false;
+		const principal = input.principal;
+		if (!principal) return false;
+		const roles = principal.roles;
+		if (!roles || roles.length === 0) return false;
+		for (const role of roles) {
+			if (!grants.has(role)) continue;
+			const granted = grants.get(role);
+			if (granted === null) return true;
+			if (granted?.has(input.action)) return true;
+		}
+		return false;
+	} };
+}
+//#endregion
+export { roles_exports as a, rolesAuthorization as i, DEFAULT_ROLE_POLICY as n, READ_ACTIONS as r, ALL_ACTIONS as t };
+
+//# sourceMappingURL=roles-vp361lTk.mjs.map

package/dist/roles-vp361lTk.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles-vp361lTk.mjs","names":[],"sources":["../src/authorization/roles.ts"],"sourcesContent":["/**\n * Role-based {@link AuthorizationProvider}. Maps each role name to the set of\n * {@link WebhooksAction}s it grants, then allows an action when *any* of the\n * principal's roles grants it.\n *\n * The policy is a flat `Record<roleName, WebhooksAction[] | \"*\">` — `\"*\"` is a\n * wildcard granting every action. When no `policy` is supplied, the built-in\n * {@link DEFAULT_ROLE_POLICY} applies (`admin`/`editor`/`viewer`).\n *\n * A `readonly` switch denies every {@link isMutatingAction mutating} action\n * regardless of role — handy for read-only mirrors or \"break glass\" lockdowns.\n *\n * @module\n */\n\nimport type { AuthorizationProvider, AuthorizeInput, WebhooksAction } from \"./contract.ts\";\nimport { isMutatingAction } from \"./contract.ts\";\n\n/** Every action in the system, used to expand non-wildcard \"all actions\" presets. */\nexport const ALL_ACTIONS: readonly WebhooksAction[] = [\n  \"application:read\",\n  \"application:create\",\n  \"application:update\",\n  \"application:delete\",\n  \"event-type:read\",\n  \"event-type:create\",\n  \"event-type:update\",\n  \"event-type:delete\",\n  \"endpoint:read\",\n  \"endpoint:create\",\n  \"endpoint:update\",\n  \"endpoint:delete\",\n  \"endpoint:rotate-secret\",\n  \"endpoint:read-secret\",\n  \"message:read\",\n  \"message:publish\",\n  \"delivery:read\",\n  \"delivery:retry\",\n  \"audit:read\",\n];\n\n/**\n * Every read-only action (the `*:read` subset of {@link ALL_ACTIONS}).\n * `endpoint:read-secret` is deliberately excluded — secret access is sensitive\n * and must be granted explicitly.\n */\nexport const READ_ACTIONS: readonly WebhooksAction[] = ALL_ACTIONS.filter((a) =>\n  a.endsWith(\":read\"),\n);\n\n/** A role policy: each role maps to an explicit action list or the `\"*\"` wildcard. */\nexport type RolePolicy = Record<string, WebhooksAction[] | \"*\">;\n\n/**\n * The default role policy applied when {@link RolesAuthorizationOptions.policy}\n * is omitted.\n *\n * - `admin` — `\"*\"`, every action.\n * - `editor` — every action (explicit list, equivalent to `admin` here).\n * - `viewer` — every `*:read` action only.\n */\nexport const DEFAULT_ROLE_POLICY: RolePolicy = {\n  admin: \"*\",\n  editor: [...ALL_ACTIONS],\n  viewer: [...READ_ACTIONS],\n};\n\n/** Options for {@link rolesAuthorization}. */\nexport interface RolesAuthorizationOptions {\n  /**\n   * Role → granted actions. `\"*\"` grants everything. Defaults to\n   * {@link DEFAULT_ROLE_POLICY} when omitted.\n   */\n  policy?: RolePolicy;\n  /**\n   * When `true`, every {@link isMutatingAction mutating} action is denied\n   * regardless of the principal's roles.\n   * @default false\n   */\n  readonly?: boolean;\n}\n\n/**\n * Create a role-based {@link AuthorizationProvider}.\n *\n * Decision order:\n * 1. If `readonly` and the action mutates → **deny**.\n * 2. If the principal is `null` → **deny**.\n * 3. If any of the principal's roles grants the action (via `\"*\"` or an explicit\n *    list) → **allow**; otherwise **deny**.\n *\n * @example\n * ```ts\n * import { rolesAuthorization } from \"@xtandard/webhooks/authorization/roles\";\n *\n * // Built-in admin/editor/viewer policy:\n * const authz = rolesAuthorization();\n *\n * // Custom policy:\n * const custom = rolesAuthorization({\n *   policy: {\n *     ops: [\"delivery:read\", \"delivery:retry\", \"endpoint:read\"],\n *     auditor: [\"audit:read\"],\n *   },\n * });\n * ```\n */\nexport function rolesAuthorization(options: RolesAuthorizationOptions = {}): AuthorizationProvider {\n  const policy = options.policy ?? DEFAULT_ROLE_POLICY;\n  const readonly = options.readonly ?? false;\n\n  // Pre-compute each role's granted action set for O(1) lookups. A role mapped\n  // to \"*\" is recorded as `null` (wildcard).\n  const grants = new Map<string, Set<WebhooksAction> | null>();\n  for (const [role, actions] of Object.entries(policy)) {\n    grants.set(role, actions === \"*\" ? null : new Set(actions));\n  }\n\n  return {\n    async authorize(input: AuthorizeInput): Promise<boolean> {\n      if (readonly && isMutatingAction(input.action)) return false;\n\n      const principal = input.principal;\n      if (!principal) return false;\n\n      const roles = principal.roles;\n      if (!roles || roles.length === 0) return false;\n\n      for (const role of roles) {\n        if (!grants.has(role)) continue;\n        const granted = grants.get(role);\n        if (granted === null) return true; // wildcard\n        if (granted?.has(input.action)) return true;\n      }\n      return false;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;AAmBA,MAAa,cAAyC;CACpD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;;;;;AAOA,MAAa,eAA0C,YAAY,QAAQ,MACzE,EAAE,SAAS,OAAO,CACpB;;;;;;;;;AAaA,MAAa,sBAAkC;CAC7C,OAAO;CACP,QAAQ,CAAC,GAAG,WAAW;CACvB,QAAQ,CAAC,GAAG,YAAY;AAC1B;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,SAAgB,mBAAmB,UAAqC,CAAC,GAA0B;CACjG,MAAM,SAAS,QAAQ,UAAU;CACjC,MAAM,WAAW,QAAQ,YAAY;CAIrC,MAAM,yBAAS,IAAI,IAAwC;CAC3D,KAAK,MAAM,CAAC,MAAM,YAAY,OAAO,QAAQ,MAAM,GACjD,OAAO,IAAI,MAAM,YAAY,MAAM,OAAO,IAAI,IAAI,OAAO,CAAC;CAG5D,OAAO,EACL,MAAM,UAAU,OAAyC;EACvD,IAAI,YAAY,iBAAiB,MAAM,MAAM,GAAG,OAAO;EAEvD,MAAM,YAAY,MAAM;EACxB,IAAI,CAAC,WAAW,OAAO;EAEvB,MAAM,QAAQ,UAAU;EACxB,IAAI,CAAC,SAAS,MAAM,WAAW,GAAG,OAAO;EAEzC,KAAK,MAAM,QAAQ,OAAO;GACxB,IAAI,CAAC,OAAO,IAAI,IAAI,GAAG;GACvB,MAAM,UAAU,OAAO,IAAI,IAAI;GAC/B,IAAI,YAAY,MAAM,OAAO;GAC7B,IAAI,SAAS,IAAI,MAAM,MAAM,GAAG,OAAO;EACzC;EACA,OAAO;CACT,EACF;AACF"}