@withpica/mcp-server 2.103.0 → 2.104.0

package/dist/tools/relationship-copy.js

@@ -0,0 +1,213 @@
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
+/**
+ * ADR-333 — plain words for a relationship (who looks after whose
+ * catalogue), as the assistant tools say them.
+ *
+ * The MCP package cannot import the app, so this keeps its own copy of what
+ * the screens say: the type labels and statuses (from
+ * lib/services/portfolio-relationship-model.ts), the screen addresses (from
+ * lib/config/relationship-paths.ts), and the status and history sentences
+ * (from app/inspect/lib/relationship-copy.ts). The tools and the screens
+ * cannot say different things without
+ * lib/services/__tests__/relationship-scope-mcp-parity.test.ts failing: it
+ * compares every constant here with the app's and runs both sentence
+ * builders over every status and event kind.
+ *
+ * Pure: no imports.
+ */
+export const GRANTABLE_RELATIONSHIP_TYPES = [
+    "co_owner",
+    "administrator",
+    "representative",
+    "viewer",
+];
+export const RELATIONSHIP_TYPE_LABELS = {
+    co_owner: "co-owner with a share",
+    administrator: "administrator",
+    representative: "representative",
+    viewer: "viewer",
+};
+export const RELATIONSHIP_STATUSES = [
+    "proposed",
+    "active",
+    "declined",
+    "revoked",
+    "stepped_down",
+    "expired",
+    "suspended",
+];
+/** What a type may do, said to the catalogue's owner. */
+export const TYPE_DOES = {
+    administrator: "can edit and register your songs and send exports for you. changes to splits or custody come to you to approve.",
+    representative: "can see and export what's in scope, and suggest changes. every change to your record comes to you to approve first.",
+    viewer: "can see and export what's in scope, and nothing else.",
+    co_owner: "can see the songs and recordings it has a share in. it can't change your facts.",
+};
+/** The same allowances, said to the organisation that holds them. */
+export const TYPE_DOES_FOR_ORG = {
+    administrator: "can edit and register their songs and send exports for them. changes to splits or custody go to them to approve.",
+    representative: "can see and export what's in scope, and suggest changes. every change to their record goes to them to approve first.",
+    viewer: "can see and export what's in scope, and nothing else.",
+    co_owner: "can see the songs and recordings it has a share in. it can't change their facts.",
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Screen addresses (paths; the tools prefix the web origin)
+// ─────────────────────────────────────────────────────────────────────────────
+export const RELATIONSHIPS_PATH = "/inspect/relationships";
+export function relationshipPath(relationshipId) {
+    return `${RELATIONSHIPS_PATH}/${encodeURIComponent(relationshipId)}`;
+}
+export const INVITATIONS_FOR_YOU_PATH = `${RELATIONSHIPS_PATH}#invitations-for-you`;
+export function relationshipActivityPath(granteeOrgId) {
+    return granteeOrgId
+        ? `${RELATIONSHIPS_PATH}/activity?org=${encodeURIComponent(granteeOrgId)}`
+        : `${RELATIONSHIPS_PATH}/activity`;
+}
+/** Hand-overs (ADR-333 D5); the app's are lib/config/handover-paths.ts. */
+export const HANDOVERS_PATH = "/inspect/handovers";
+export function handoverPath(handoverId) {
+    return `${HANDOVERS_PATH}/${encodeURIComponent(handoverId)}`;
+}
+export const NEW_HANDOVER_PATH = `${HANDOVERS_PATH}/new`;
+/** Where a relationship stands, for the side reading it. */
+export function statusLine(r, reader) {
+    const other = reader === "grantor" ? r.granteeOrgName : r.grantorOrgName;
+    const day = (iso) => (iso ? iso.slice(0, 10) : "");
+    switch (r.status) {
+        case "proposed": {
+            const lapses = r.proposalExpiresAt
+                ? ` · expires ${day(r.proposalExpiresAt)}`
+                : "";
+            return r.proposedBySide === reader
+                ? { text: `waiting for ${other} to answer${lapses}`, needsYou: false }
+                : {
+                    text: `${other} is asking · needs your answer${lapses}`,
+                    needsYou: true,
+                };
+        }
+        case "suspended":
+            return {
+                text: `paused by pica ${day(r.suspendedAt)} · it grants nothing while paused. ask pica if you have questions.`,
+                needsYou: false,
+            };
+        case "active":
+            return {
+                text: `active since ${day(r.respondedAt) || day(r.proposedAt)}${r.scope.termEndsOn ? ` · ends ${r.scope.termEndsOn}` : ""}`,
+                needsYou: false,
+            };
+        case "declined":
+            return { text: `declined ${day(r.respondedAt)}`, needsYou: false };
+        case "revoked":
+            return { text: `ended by the owner ${day(r.endedAt)}`, needsYou: false };
+        case "stepped_down":
+            return {
+                text: `${r.granteeOrgName} stepped down ${day(r.endedAt)}`,
+                needsYou: false,
+            };
+        case "expired":
+            return {
+                text: r.endReason === "proposal_unanswered"
+                    ? `lapsed unanswered ${day(r.endedAt)}`
+                    : `term ended ${day(r.endedAt)}`,
+                needsYou: false,
+            };
+    }
+}
+/** One audit row as a sentence: who did what, through which relationship. */
+export function eventLine(e) {
+    const org = e.actorSide === "grantor"
+        ? e.grantorOrgName
+        : e.actorSide === "grantee"
+            ? e.granteeOrgName
+            : null;
+    // The PICA team acts as PICA: its people are not named to customers.
+    const who = e.actorSide === "platform"
+        ? "pica"
+        : e.actorDisplayName
+            ? org
+                ? `${e.actorDisplayName} (${org})`
+                : e.actorDisplayName
+            : (org ?? "pica");
+    const type = RELATIONSHIP_TYPE_LABELS[e.type] ?? humanise(e.type);
+    switch (e.kind) {
+        case "proposed":
+            return `${who} proposed ${e.granteeOrgName} as ${type}`;
+        case "accepted":
+            return `${who} accepted ${e.granteeOrgName} as ${type}`;
+        case "declined":
+            return `${who} declined`;
+        case "scope_changed":
+            return `${who} changed what's covered`;
+        case "revoked":
+            return `${who} ended the relationship`;
+        case "stepped_down":
+            return `${who} stepped down`;
+        case "expired":
+            return e.reason === "proposal_unanswered"
+                ? "the request lapsed unanswered"
+                : "the term ended";
+        case "term_ending_soon": {
+            const on = detailDate(e, "term_ends_on") ?? e.scope.termEndsOn;
+            return `the term ends on ${on ?? "its end date"}`;
+        }
+        case "proposal_expiring_soon": {
+            const on = detailDate(e, "proposal_expires_at");
+            return `the request lapses${on ? ` on ${on}` : " soon"} if nobody answers`;
+        }
+        case "suspended":
+            return "pica paused it: it grants nothing while paused";
+        case "reinstated":
+            return "pica resumed it";
+        case "acted":
+            return `${who} ${humanise(e.action) || "acted"}${e.entityType ? ` · ${humanise(e.entityType)}` : ""}`;
+        default:
+            // A kind added after this copy: said by its name, never dropped.
+            return `${who} · ${humanise(e.kind)}`;
+    }
+}
+function detailDate(e, key) {
+    const v = e.detail?.[key];
+    return typeof v === "string" && v.length >= 10 ? v.slice(0, 10) : null;
+}
+function humanise(s) {
+    return (s ?? "").replace(/_/g, " ").trim();
+}
+/**
+ * The scope in one line for the side reading it: what, which side, where,
+ * when, money and (administrators) the directory. Territories are ISO codes
+ * here ("GB, IE"); the screens spell the country names.
+ */
+export function scopeSummary(scope, type, reader) {
+    const whose = reader.side === "grantor" ? "your" : `${reader.grantorName}'s`;
+    const songs = scope.workIds?.length ?? scope.songsChosen ?? 0;
+    const recordings = scope.recordingIds?.length ?? scope.recordingsChosen ?? 0;
+    const count = (n, one) => `${n} ${one}${n === 1 ? "" : "s"}`;
+    const what = scope.catalogue === "whole"
+        ? `${whose} whole catalogue`
+        : [
+            songs > 0 ? count(songs, "song") : null,
+            recordings > 0 ? count(recordings, "recording") : null,
+        ]
+            .filter(Boolean)
+            .join(" and ") + ` from ${whose} catalogue`;
+    const half = scope.half === "both"
+        ? "songs and recordings"
+        : scope.half === "composition"
+            ? "the song side only"
+            : "the recording side only";
+    const where = scope.territories.includes("WW")
+        ? "worldwide"
+        : scope.territories.join(", ");
+    const when = (scope.termStartsOn ? `from ${scope.termStartsOn}` : "from acceptance") +
+        (scope.termEndsOn ? ` until ${scope.termEndsOn}` : ", no end date");
+    const money = scope.money
+        ? "can see statements"
+        : "can't see statements or earnings";
+    const directory = type === "administrator"
+        ? scope.directory
+            ? "; can list songs in the public directory"
+            : "; can't list songs in the public directory"
+        : "";
+    return `${what}, ${half}, ${where}, ${when}; ${money}${directory}`;
+}
+//# sourceMappingURL=relationship-copy.js.map

package/dist/tools/relationship-copy.js.map

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

package/dist/tools/relationship-scope.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The scope of a portfolio relationship, as the assistant tools accept it
+ * (ADR-333 D3). The main MCP server cannot import the app, so this mirrors
+ * `relationshipScopeSchema` in lib/services/portfolio-relationship-model.ts
+ * with snake_case names. lib/services/__tests__/relationship-scope-mcp-
+ * parity.test.ts fails if a field, an allowed value or a limit drifts.
+ *
+ * Every field is optional: the app fills the defaults (whole catalogue, both
+ * halves, worldwide, no end date, money on only for an administrator,
+ * directory off). The rules that join two fields (for example "worldwide
+ * cannot be combined with other territories") are enforced by the app, which
+ * refuses with a plain reason; the descriptions below state them.
+ *
+ * Deliberately has no imports, so the parity test can load it directly.
+ */
+export declare const SCOPE_HALVES: readonly ["both", "composition", "master"];
+export declare const SCOPE_CATALOGUES: readonly ["whole", "chosen"];
+export declare const SCOPE_MAX_TERRITORIES = 300;
+export declare const SCOPE_MAX_ITEMS = 5000;
+export declare const SCOPE_TERRITORY_PATTERN = "^[A-Z]{2}$";
+export declare const SCOPE_DATE_PATTERN = "^\\d{4}-\\d{2}-\\d{2}$";
+/** The tool argument name for each field of the app's scope. */
+export declare const SCOPE_FIELD_NAMES: {
+    readonly half: "half";
+    readonly territories: "territories";
+    readonly term_starts_on: "termStartsOn";
+    readonly term_ends_on: "termEndsOn";
+    readonly money: "money";
+    readonly directory: "directory";
+    readonly catalogue: "catalogue";
+    readonly work_ids: "workIds";
+    readonly recording_ids: "recordingIds";
+};
+export type ScopeArgName = keyof typeof SCOPE_FIELD_NAMES;
+/** JSON Schema for the optional `scope` argument of grant, invite and answer. */
+export declare const RELATIONSHIP_SCOPE_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly description: string;
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly half: {
+            readonly type: "string";
+            readonly enum: readonly ["both", "composition", "master"];
+            readonly description: "Which half of the songs: both, composition (the song and its publishing) or master (the recordings).";
+        };
+        readonly territories: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly pattern: "^[A-Z]{2}$";
+            };
+            readonly minItems: 1;
+            readonly maxItems: 300;
+            readonly description: "Countries covered. Only [\"WW\"] (worldwide) is accepted today: limiting a relationship to some countries is not available yet, and any other value is refused.";
+        };
+        readonly term_starts_on: {
+            readonly type: readonly ["string", "null"];
+            readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+            readonly description: "First day covered, YYYY-MM-DD (UTC). Leave out or null to start when it is accepted.";
+        };
+        readonly term_ends_on: {
+            readonly type: readonly ["string", "null"];
+            readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+            readonly description: "Last day covered, YYYY-MM-DD (UTC), inclusive. Leave out or null for until revoked. On that date access ends by itself.";
+        };
+        readonly money: {
+            readonly type: "boolean";
+            readonly description: "true lets the organisation see statements and earnings in scope.";
+        };
+        readonly directory: {
+            readonly type: "boolean";
+            readonly description: "true lets an administrator list or hide songs in the public directory and answer enquiries. Administrators only.";
+        };
+        readonly catalogue: {
+            readonly type: "string";
+            readonly enum: readonly ["whole", "chosen"];
+            readonly description: "whole for the whole catalogue, or chosen for only the songs and recordings named in work_ids and recording_ids.";
+        };
+        readonly work_ids: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly format: "uuid";
+            };
+            readonly maxItems: 5000;
+            readonly description: "Songs covered when catalogue is chosen (ids from pica_works_query). Not allowed for a master-only scope.";
+        };
+        readonly recording_ids: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly format: "uuid";
+            };
+            readonly maxItems: 5000;
+            readonly description: "Recordings covered when catalogue is chosen (ids from pica_recordings_query). Not allowed for a composition-only scope.";
+        };
+    };
+};
+/**
+ * Convert the tool's `scope` argument to the app's field names. Unknown keys
+ * are dropped here; the schema above already refuses them at the MCP layer.
+ */
+export declare function scopeArgToApi(scope: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+//# sourceMappingURL=relationship-scope.d.ts.map

package/dist/tools/relationship-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-scope.d.ts","sourceRoot":"","sources":["../../src/tools/relationship-scope.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH,eAAO,MAAM,YAAY,4CAA6C,CAAC;AACvE,eAAO,MAAM,gBAAgB,8BAA+B,CAAC;AAC7D,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,eAAO,MAAM,eAAe,OAAO,CAAC;AACpC,eAAO,MAAM,uBAAuB,eAAe,CAAC;AACpD,eAAO,MAAM,kBAAkB,2BAA2B,CAAC;AAE3D,gEAAgE;AAChE,eAAO,MAAM,iBAAiB;;;;;;;;;;CAUpB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,iBAAiB,CAAC;AAE1D,iFAAiF;AACjF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiElC,CAAC;AAEX;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACzC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAOrC"}

package/dist/tools/relationship-scope.js

@@ -0,0 +1,106 @@
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
+/**
+ * The scope of a portfolio relationship, as the assistant tools accept it
+ * (ADR-333 D3). The main MCP server cannot import the app, so this mirrors
+ * `relationshipScopeSchema` in lib/services/portfolio-relationship-model.ts
+ * with snake_case names. lib/services/__tests__/relationship-scope-mcp-
+ * parity.test.ts fails if a field, an allowed value or a limit drifts.
+ *
+ * Every field is optional: the app fills the defaults (whole catalogue, both
+ * halves, worldwide, no end date, money on only for an administrator,
+ * directory off). The rules that join two fields (for example "worldwide
+ * cannot be combined with other territories") are enforced by the app, which
+ * refuses with a plain reason; the descriptions below state them.
+ *
+ * Deliberately has no imports, so the parity test can load it directly.
+ */
+export const SCOPE_HALVES = ["both", "composition", "master"];
+export const SCOPE_CATALOGUES = ["whole", "chosen"];
+export const SCOPE_MAX_TERRITORIES = 300;
+export const SCOPE_MAX_ITEMS = 5000;
+export const SCOPE_TERRITORY_PATTERN = "^[A-Z]{2}$";
+export const SCOPE_DATE_PATTERN = "^\\d{4}-\\d{2}-\\d{2}$";
+/** The tool argument name for each field of the app's scope. */
+export const SCOPE_FIELD_NAMES = {
+    half: "half",
+    territories: "territories",
+    term_starts_on: "termStartsOn",
+    term_ends_on: "termEndsOn",
+    money: "money",
+    directory: "directory",
+    catalogue: "catalogue",
+    work_ids: "workIds",
+    recording_ids: "recordingIds",
+};
+/** JSON Schema for the optional `scope` argument of grant, invite and answer. */
+export const RELATIONSHIP_SCOPE_INPUT_SCHEMA = {
+    type: "object",
+    description: "What the relationship covers. Leave out any field to use the default: the whole catalogue, " +
+        "both halves, worldwide, until revoked, statements hidden (shown by default only to an " +
+        "administrator), directory off.",
+    additionalProperties: false,
+    properties: {
+        half: {
+            type: "string",
+            enum: [...SCOPE_HALVES],
+            description: "Which half of the songs: both, composition (the song and its publishing) or master (the recordings).",
+        },
+        territories: {
+            type: "array",
+            items: { type: "string", pattern: SCOPE_TERRITORY_PATTERN },
+            minItems: 1,
+            maxItems: SCOPE_MAX_TERRITORIES,
+            description: 'Countries covered. Only ["WW"] (worldwide) is accepted today: limiting a relationship to some countries is not available yet, and any other value is refused.',
+        },
+        term_starts_on: {
+            type: ["string", "null"],
+            pattern: SCOPE_DATE_PATTERN,
+            description: "First day covered, YYYY-MM-DD (UTC). Leave out or null to start when it is accepted.",
+        },
+        term_ends_on: {
+            type: ["string", "null"],
+            pattern: SCOPE_DATE_PATTERN,
+            description: "Last day covered, YYYY-MM-DD (UTC), inclusive. Leave out or null for until revoked. On that date access ends by itself.",
+        },
+        money: {
+            type: "boolean",
+            description: "true lets the organisation see statements and earnings in scope.",
+        },
+        directory: {
+            type: "boolean",
+            description: "true lets an administrator list or hide songs in the public directory and answer enquiries. Administrators only.",
+        },
+        catalogue: {
+            type: "string",
+            enum: [...SCOPE_CATALOGUES],
+            description: "whole for the whole catalogue, or chosen for only the songs and recordings named in work_ids and recording_ids.",
+        },
+        work_ids: {
+            type: "array",
+            items: { type: "string", format: "uuid" },
+            maxItems: SCOPE_MAX_ITEMS,
+            description: "Songs covered when catalogue is chosen (ids from pica_works_query). Not allowed for a master-only scope.",
+        },
+        recording_ids: {
+            type: "array",
+            items: { type: "string", format: "uuid" },
+            maxItems: SCOPE_MAX_ITEMS,
+            description: "Recordings covered when catalogue is chosen (ids from pica_recordings_query). Not allowed for a composition-only scope.",
+        },
+    },
+};
+/**
+ * Convert the tool's `scope` argument to the app's field names. Unknown keys
+ * are dropped here; the schema above already refuses them at the MCP layer.
+ */
+export function scopeArgToApi(scope) {
+    if (!scope)
+        return undefined;
+    const out = {};
+    for (const [arg, api] of Object.entries(SCOPE_FIELD_NAMES)) {
+        if (scope[arg] !== undefined)
+            out[api] = scope[arg];
+    }
+    return out;
+}
+//# sourceMappingURL=relationship-scope.js.map

package/dist/tools/relationship-scope.js.map

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

package/dist/tools/relationships.d.ts

@@ -0,0 +1,64 @@
+/**
+ * ADR-333 — who looks after whose catalogue, for assistants.
+ *
+ * Owner side: pica_relationships_list, _answer, _grant, _revoke, _activity.
+ * Organisation side: pica_portfolio_list, _briefing, _invite and
+ * pica_relationships_step_down (list, answer and activity serve both sides).
+ *
+ * Each tool calls one of pica-b5's /api/admin/relationships/** or
+ * /api/admin/portfolio routes, which hold no rules of their own: the 1.1
+ * service decides every step and refuses with a code and a plain sentence,
+ * which these tools pass on as they are.
+ *
+ * Accepting, changing, revoking and an owner's invitation give or take away
+ * access, so they are the person's own decision (ADR-333 D1):
+ *  - from a connected app or agent grant, pica_relationships_answer, _grant
+ *    and _revoke are `approvalMode: "human"`: the MCP route stages an
+ *    approval for the person, and on approval
+ *    lib/services/relationship-approvals.ts runs the step through the
+ *    service, never this file;
+ *  - from the in-app assistant (not staged), the route refuses those steps
+ *    as HUMAN_CONFIRMATION_REQUIRED and the tool gives the screen to do it on.
+ * Declining, stepping down and an organisation's invitation take nothing
+ * from anyone, so an agent may do them.
+ *
+ * Every step sends the version of the relationship the caller read
+ * (expected_version). If the terms changed since, nothing happens and the
+ * tool returns the current terms to read again.
+ */
+import { type PicaClient } from "@withpica/mcp-sdk";
+import type { PortfolioClientRecord } from "@withpica/mcp-sdk";
+import type { ToolDefinition, ToolExecutor } from "./index.js";
+/** 1.1's MAX_PAGE_LIMIT: a relationship page reads limit + 1 rows. */
+export declare const RELATIONSHIP_PAGE_MAX = 999;
+/** pica-2f's 1.4 page cap. */
+export declare const PORTFOLIO_PAGE_MAX = 25;
+/** The scope fields a client can be asked for: what they cover comes from the client. */
+export declare const INVITE_SCOPE_FIELDS: readonly ["half", "territories", "term_starts_on", "term_ends_on"];
+/** `https://withpica.com/api` → `https://withpica.com`. */
+export declare function webOrigin(apiUrl: string | undefined): string;
+/** One client as a line: who, as what, and what needs attention. */
+export declare function portfolioLine(c: PortfolioClientRecord): string;
+export declare class RelationshipTools {
+    private readonly pica;
+    private readonly origin;
+    constructor(pica: PicaClient, apiUrl?: string);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private list;
+    private activity;
+    private portfolioList;
+    private portfolioBriefing;
+    private portfolio;
+    private answer;
+    private stepResult;
+    private grant;
+    private invite;
+    private sendInvite;
+    private revoke;
+    private stepDown;
+    private end;
+}
+//# sourceMappingURL=relationships.d.ts.map

package/dist/tools/relationships.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../src/tools/relationships.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,KAAK,EAGV,qBAAqB,EAKtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AA0B3E,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,8BAA8B;AAC9B,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAGrC,yFAAyF;AACzF,eAAO,MAAM,mBAAmB,oEAKtB,CAAC;AAIX,2DAA2D;AAC3D,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAG5D;AAiSD,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAsC9D;AAED,qBAAa,iBAAiB;IAI1B,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAGb,IAAI,EAAE,UAAU,EACjC,MAAM,CAAC,EAAE,MAAM;IAKjB,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YA4V3D,IAAI;YAmFJ,QAAQ;YAyER,aAAa;YAIb,iBAAiB;YAIjB,SAAS;YAiET,MAAM;IA4HpB,OAAO,CAAC,UAAU;YAoBJ,KAAK;YAIL,MAAM;YAIN,UAAU;YA+CV,MAAM;YAIN,QAAQ;YAIR,GAAG;CAqDlB"}