@pingroom/sdk 0.1.0 → 0.3.1

package/dist/liveActivity.js

@@ -0,0 +1,83 @@
+/**
+ * Live Activity template builders for the PingRoom agent SDK.
+ *
+ * IMPORTANT — these builders do NOT start an activity. The server starts,
+ * updates, and ends Live Activities only from a **live-status stream**: a
+ * `live_status` object sent either to a room's incoming webhook or to the agent
+ * route (see https://pingroom.io/liveactivities.md). A `live_activity` block
+ * placed in a `broadcast()` / `ping()` `data` object is carried as opaque
+ * structured data — clients only honor the server-built, top-level
+ * `live_activity` push block.
+ *
+ * These builders produce that `{ attributes, content_state }` block in the
+ * frozen native shape (mobile/modules/live-activity/src/LiveActivity.types.ts,
+ * LIVE_ACTIVITY_TEMPLATES.md). Use them when you need the native contract —
+ * e.g. constructing expected payloads in tests or tooling that speaks the
+ * push-layer shape.
+ *
+ * To actually drive a Live Activity, use `liveStatus.*` + `pr.live.push()`
+ * (agent credential, `pingroom:live:write`) or `sendIncomingWebhook()`.
+ */
+function build(template, id, state) {
+    const { title, message, status, accentOverride, ...rest } = state;
+    return {
+        live_activity: {
+            attributes: {
+                kind: id.kind ?? 'agent',
+                template,
+                roomCode: id.roomCode,
+                roomName: id.roomName,
+                roomColor: id.roomColor,
+                ...(id.roomIconSvg ? { roomIconSvg: id.roomIconSvg } : {}),
+                ...(id.correlationId ? { correlationId: id.correlationId } : {}),
+                ...(id.agentId ? { agentId: id.agentId } : {}),
+            },
+            content_state: {
+                status: status ?? 'open',
+                title,
+                message: message ?? '',
+                ...(accentOverride ? { accentOverride } : {}),
+                ...rest,
+                updatedAt: Math.floor(Date.now() / 1000),
+            },
+        },
+    };
+}
+export const liveActivity = {
+    /** Single hero line + status dot; optional live ETA (`etaAt`, epoch seconds). */
+    status(input) {
+        const { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind, ...state } = input;
+        return build('status', { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind }, state);
+    },
+    /** Checkpoint rail — the understand → plan → doc pattern. */
+    steps(input) {
+        const { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind, ...state } = input;
+        return build('steps', { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind }, state);
+    },
+    /** Determinate progress bar (0..1), optional `etaAt` countdown. */
+    progress(input) {
+        const { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind, ...state } = input;
+        return build('progress', { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind }, state);
+    },
+    /** Up to 3 live counters. */
+    metrics(input) {
+        const { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind, ...state } = input;
+        return build('metrics', { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind }, state);
+    },
+    /** Big timer counting down to `deadlineAt` (epoch seconds). */
+    countdown(input) {
+        const { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind, ...state } = input;
+        return build('countdown', { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind }, state);
+    },
+    /** Lock-screen ask: prompt + up to 4 options; `deadlineAt` shows time-left. */
+    question(input) {
+        const { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind, ...state } = input;
+        return build('question', { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind }, state);
+    },
+    /** Head-to-head: left · center · right. */
+    matchup(input) {
+        const { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind, ...state } = input;
+        return build('matchup', { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind }, state);
+    },
+};
+//# sourceMappingURL=liveActivity.js.map

package/dist/liveActivity.js.map

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

package/dist/liveStatus.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Live-status streams — the wire contract for driving a Live Activity.
+ *
+ * A stream is keyed by `correlation_id`: the first ping starts a live card on
+ * every room member's lock screen (one alert), further `running` pings move it
+ * silently, and the first `done`/`failed` sends one completion alert and ends
+ * it. See https://pingroom.io/liveactivities.md.
+ *
+ * Three producers speak this contract. This SDK reaches the two machine ones:
+ *   - a room's **incoming webhook** (Pro) — `sendIncomingWebhook()`
+ *   - an **agent credential** — `pr.live.*` (needs `pingroom:live:write`)
+ *
+ * The third is a signed-in person driving a stream from the app composer over
+ * `POST /api/rooms/{inviteCode}/live` with their own Human JWT. It sends this
+ * same body minus `live_status.agent_id` (stripped server-side), so these
+ * builders describe it too — but it is not an agent route and has no client
+ * here.
+ *
+ * Not to be confused with `liveActivity.*` in ./liveActivity.ts, which builds
+ * the frozen *native* `{ attributes, content_state }` push shape for tests and
+ * tooling. These builders produce the `live_status` object you actually send.
+ */
+import type { LiveActivityTemplate } from './liveActivity.js';
+export type LiveStatusState = 'running' | 'done' | 'failed';
+/** Legacy rendering category. Prefer `template`; `alert` selects urgent styling. */
+export type LiveStatusCategory = 'status' | 'steps' | 'alert';
+export interface LiveStatusMetric {
+    label: string;
+    value: string;
+}
+export interface LiveStatusOption {
+    value: string;
+    label: string;
+}
+export interface LiveStatusSide {
+    label: string;
+    value: string;
+    iconSvg?: string;
+}
+/**
+ * The `live_status` object. Only `state` is required; every other field is read
+ * by the template you selected.
+ *
+ * `template` and `steps` are fixed at stream creation — a later ping cannot
+ * re-template a running card. Content set at creation is sticky, so a sparse
+ * update carrying just `progress` keeps rendering the full template. The
+ * terminal leg is sticky too: `{ state: 'done' }` alone keeps the scoreboard,
+ * metrics grid, deadline and accent on the final frame.
+ */
+export interface LiveStatus {
+    state: LiveStatusState;
+    template?: LiveActivityTemplate;
+    category?: LiveStatusCategory;
+    message?: string;
+    /** 0..1 — the progress bar / Dynamic Island gauge. */
+    progress?: number;
+    /** 2–8 labels. Required on the first ping of a `steps` stream; immutable after. */
+    steps?: string[];
+    /** Index into `steps`; the only mutable steps field. */
+    current_step?: number;
+    /** Up to 3 counters, for the `metrics` template. */
+    metrics?: LiveStatusMetric[];
+    /** Epoch seconds the `countdown` template counts down to. */
+    deadline_at?: number;
+    /** Epoch seconds; renders a live ETA on `status`/`progress`. */
+    eta_at?: number;
+    /** The ask, for the `question` template. */
+    prompt?: string;
+    /** Up to 4 choices, for the `question` template. */
+    options?: LiveStatusOption[];
+    left?: LiveStatusSide;
+    right?: LiveStatusSide;
+    center?: string;
+    /** Hex `#rrggbb` — a semantic accent for one frame (e.g. deadline red). */
+    accent_override?: string;
+    agent_id?: string;
+}
+/** The full body of a live-status ping. */
+export interface LiveStatusPing {
+    correlation_id: string;
+    live_status: LiveStatus;
+    title?: string;
+    /** Quick-action slot 1–4 supplying the icon and sound. */
+    action?: number;
+    data?: Record<string, unknown>;
+    requires_ack?: boolean;
+    ack_timeout_seconds?: number;
+}
+export interface LiveStatusResult {
+    notification_id: string;
+    correlation_id: string;
+    /** `started` on creation, then `running` / `done` / `failed`. */
+    state: string;
+    idempotent: boolean;
+    action_state?: unknown;
+}
+/**
+ * The read-back shape from `GET .../live/{correlationId}`.
+ *
+ * EVERY stored `live_status` field is returned, not a step/progress subset — a
+ * `matchup` / `metrics` / `countdown` / `question` stream would otherwise be
+ * unresumable after a producer restart. Fields you never set come back as
+ * `null` rather than being omitted, so read them defensively.
+ *
+ * The server-side ownership stamps (`_webhook` / `_agent` / `_user`) are
+ * deliberately NOT returned — they are the authorization record, not client
+ * state.
+ */
+export interface LiveStatusSnapshot {
+    notification_id: string;
+    correlation_id: string;
+    state: string | null;
+    progress: number | null;
+    message: string | null;
+    category: LiveStatusCategory | null;
+    template: LiveActivityTemplate | null;
+    agent_id: string | null;
+    accent_override: string | null;
+    eta_at: number | null;
+    deadline_at: number | null;
+    metrics: LiveStatusMetric[] | null;
+    prompt: string | null;
+    options: LiveStatusOption[] | null;
+    left: LiveStatusSide | null;
+    right: LiveStatusSide | null;
+    center: string | null;
+    steps: string[] | null;
+    current_step: number | null;
+    action_state?: unknown;
+    updated_at: string | null;
+}
+type Rest = Omit<LiveStatusPing, 'correlation_id' | 'live_status'>;
+/**
+ * Builders for the common stream shapes. Each returns a body you can hand to
+ * `pr.live.push()` or `sendIncomingWebhook()`.
+ */
+export declare const liveStatus: {
+    /** Default template: a title line plus a status dot, with optional progress. */
+    status(correlationId: string, live: Omit<LiveStatus, "template">, rest?: Rest): LiveStatusPing;
+    /** A segmented step tracker. `steps` is required on the first ping. */
+    steps(correlationId: string, live: Omit<LiveStatus, "template">, rest?: Rest): LiveStatusPing;
+    /** A determinate progress bar with an optional live ETA. */
+    progress(correlationId: string, live: Omit<LiveStatus, "template">, rest?: Rest): LiveStatusPing;
+    /** Up to 3 labelled counters. */
+    metrics(correlationId: string, live: Omit<LiveStatus, "template">, rest?: Rest): LiveStatusPing;
+    /** A large live timer counting down to `deadline_at`. */
+    countdown(correlationId: string, live: Omit<LiveStatus, "template">, rest?: Rest): LiveStatusPing;
+    /** A prompt with up to 4 options shown on the lock screen. */
+    question(correlationId: string, live: Omit<LiveStatus, "template">, rest?: Rest): LiveStatusPing;
+    /** Two sides plus a center score/clock. */
+    matchup(correlationId: string, live: Omit<LiveStatus, "template">, rest?: Rest): LiveStatusPing;
+    /**
+     * An urgent stream, delivered time-sensitive from the start so it breaks
+     * through Focus.
+     *
+     * This is a `category`, not a `template`: `alert` has no template equivalent,
+     * and it is the only way to start time-sensitive WITHOUT also setting
+     * `requires_ack` (which demands somebody tap). Fixed at creation, like
+     * `template`.
+     */
+    alert(correlationId: string, live: Omit<LiveStatus, "template" | "category">, rest?: Rest): LiveStatusPing;
+    /** Finish a stream. The one alert your stream earns. */
+    done(correlationId: string, message?: string, rest?: Rest): LiveStatusPing;
+    /** Finish a stream unsuccessfully. */
+    failed(correlationId: string, message?: string, rest?: Rest): LiveStatusPing;
+};
+export {};
+//# sourceMappingURL=liveStatus.d.ts.map

package/dist/liveStatus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveStatus.d.ts","sourceRoot":"","sources":["../src/liveStatus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE5D,oFAAoF;AACpF,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;AAE9D,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,eAAe,CAAC;IACvB,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC7B,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC7B,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,2CAA2C;AAC3C,MAAM,WAAW,cAAc;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACpC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACtC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC;IACnC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC;IACnC,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5B,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACvB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,KAAK,IAAI,GAAG,IAAI,CAAC,cAAc,EAAE,gBAAgB,GAAG,aAAa,CAAC,CAAC;AAQnE;;;GAGG;AACH,eAAO,MAAM,UAAU;IACrB,gFAAgF;0BAC1D,MAAM,QAAQ,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,SAAS,IAAI,GAAG,cAAc;IAI9F,uEAAuE;yBAClD,MAAM,QAAQ,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,SAAS,IAAI,GAAG,cAAc;IAI7F,4DAA4D;4BACpC,MAAM,QAAQ,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,SAAS,IAAI,GAAG,cAAc;IAIhG,iCAAiC;2BACV,MAAM,QAAQ,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,SAAS,IAAI,GAAG,cAAc;IAI/F,yDAAyD;6BAChC,MAAM,QAAQ,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,SAAS,IAAI,GAAG,cAAc;IAIjG,8DAA8D;4BACtC,MAAM,QAAQ,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,SAAS,IAAI,GAAG,cAAc;IAIhG,2CAA2C;2BACpB,MAAM,QAAQ,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,SAAS,IAAI,GAAG,cAAc;IAI/F;;;;;;;;OAQG;yBACkB,MAAM,QAAQ,IAAI,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,CAAC,SAAS,IAAI,GAAG,cAAc;IAI1G,wDAAwD;wBACpC,MAAM,YAAY,MAAM,SAAS,IAAI,GAAG,cAAc;IAI1E,sCAAsC;0BAChB,MAAM,YAAY,MAAM,SAAS,IAAI,GAAG,cAAc;CAG7E,CAAC"}

package/dist/liveStatus.js

@@ -0,0 +1,82 @@
+/**
+ * Live-status streams — the wire contract for driving a Live Activity.
+ *
+ * A stream is keyed by `correlation_id`: the first ping starts a live card on
+ * every room member's lock screen (one alert), further `running` pings move it
+ * silently, and the first `done`/`failed` sends one completion alert and ends
+ * it. See https://pingroom.io/liveactivities.md.
+ *
+ * Three producers speak this contract. This SDK reaches the two machine ones:
+ *   - a room's **incoming webhook** (Pro) — `sendIncomingWebhook()`
+ *   - an **agent credential** — `pr.live.*` (needs `pingroom:live:write`)
+ *
+ * The third is a signed-in person driving a stream from the app composer over
+ * `POST /api/rooms/{inviteCode}/live` with their own Human JWT. It sends this
+ * same body minus `live_status.agent_id` (stripped server-side), so these
+ * builders describe it too — but it is not an agent route and has no client
+ * here.
+ *
+ * Not to be confused with `liveActivity.*` in ./liveActivity.ts, which builds
+ * the frozen *native* `{ attributes, content_state }` push shape for tests and
+ * tooling. These builders produce the `live_status` object you actually send.
+ */
+const ping = (correlationId, live, rest = {}) => ({
+    correlation_id: correlationId,
+    live_status: live,
+    ...rest,
+});
+/**
+ * Builders for the common stream shapes. Each returns a body you can hand to
+ * `pr.live.push()` or `sendIncomingWebhook()`.
+ */
+export const liveStatus = {
+    /** Default template: a title line plus a status dot, with optional progress. */
+    status(correlationId, live, rest) {
+        return ping(correlationId, { template: 'status', ...live }, rest);
+    },
+    /** A segmented step tracker. `steps` is required on the first ping. */
+    steps(correlationId, live, rest) {
+        return ping(correlationId, { template: 'steps', ...live }, rest);
+    },
+    /** A determinate progress bar with an optional live ETA. */
+    progress(correlationId, live, rest) {
+        return ping(correlationId, { template: 'progress', ...live }, rest);
+    },
+    /** Up to 3 labelled counters. */
+    metrics(correlationId, live, rest) {
+        return ping(correlationId, { template: 'metrics', ...live }, rest);
+    },
+    /** A large live timer counting down to `deadline_at`. */
+    countdown(correlationId, live, rest) {
+        return ping(correlationId, { template: 'countdown', ...live }, rest);
+    },
+    /** A prompt with up to 4 options shown on the lock screen. */
+    question(correlationId, live, rest) {
+        return ping(correlationId, { template: 'question', ...live }, rest);
+    },
+    /** Two sides plus a center score/clock. */
+    matchup(correlationId, live, rest) {
+        return ping(correlationId, { template: 'matchup', ...live }, rest);
+    },
+    /**
+     * An urgent stream, delivered time-sensitive from the start so it breaks
+     * through Focus.
+     *
+     * This is a `category`, not a `template`: `alert` has no template equivalent,
+     * and it is the only way to start time-sensitive WITHOUT also setting
+     * `requires_ack` (which demands somebody tap). Fixed at creation, like
+     * `template`.
+     */
+    alert(correlationId, live, rest) {
+        return ping(correlationId, { category: 'alert', ...live }, rest);
+    },
+    /** Finish a stream. The one alert your stream earns. */
+    done(correlationId, message, rest) {
+        return ping(correlationId, { state: 'done', ...(message ? { message } : {}) }, rest);
+    },
+    /** Finish a stream unsuccessfully. */
+    failed(correlationId, message, rest) {
+        return ping(correlationId, { state: 'failed', ...(message ? { message } : {}) }, rest);
+    },
+};
+//# sourceMappingURL=liveStatus.js.map

package/dist/liveStatus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveStatus.js","sourceRoot":"","sources":["../src/liveStatus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA2HH,MAAM,IAAI,GAAG,CAAC,aAAqB,EAAE,IAAgB,EAAE,OAAa,EAAE,EAAkB,EAAE,CAAC,CAAC;IAC1F,cAAc,EAAE,aAAa;IAC7B,WAAW,EAAE,IAAI;IACjB,GAAG,IAAI;CACR,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,gFAAgF;IAChF,MAAM,CAAC,aAAqB,EAAE,IAAkC,EAAE,IAAW;QAC3E,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACpE,CAAC;IAED,uEAAuE;IACvE,KAAK,CAAC,aAAqB,EAAE,IAAkC,EAAE,IAAW;QAC1E,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACnE,CAAC;IAED,4DAA4D;IAC5D,QAAQ,CAAC,aAAqB,EAAE,IAAkC,EAAE,IAAW;QAC7E,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACtE,CAAC;IAED,iCAAiC;IACjC,OAAO,CAAC,aAAqB,EAAE,IAAkC,EAAE,IAAW;QAC5E,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACrE,CAAC;IAED,yDAAyD;IACzD,SAAS,CAAC,aAAqB,EAAE,IAAkC,EAAE,IAAW;QAC9E,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACvE,CAAC;IAED,8DAA8D;IAC9D,QAAQ,CAAC,aAAqB,EAAE,IAAkC,EAAE,IAAW;QAC7E,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACtE,CAAC;IAED,2CAA2C;IAC3C,OAAO,CAAC,aAAqB,EAAE,IAAkC,EAAE,IAAW;QAC5E,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACrE,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,aAAqB,EAAE,IAA+C,EAAE,IAAW;QACvF,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACnE,CAAC;IAED,wDAAwD;IACxD,IAAI,CAAC,aAAqB,EAAE,OAAgB,EAAE,IAAW;QACvD,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACvF,CAAC;IAED,sCAAsC;IACtC,MAAM,CAAC,aAAqB,EAAE,OAAgB,EAAE,IAAW;QACzD,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACzF,CAAC;CACF,CAAC"}