@brass-build/client 0.2.0 → 0.4.0

package/dist/acting-organization.d.ts

@@ -0,0 +1,131 @@
+export declare function storeActingOrganization(appId: string, organizationId: string): void;
+export declare function readActingOrganization(appId: string): string | null;
+export declare function clearActingOrganization(appId: string): void;
+export type ResolveOutcome = {
+    kind: 'resolved';
+    organizationId: string;
+    organizationName: string;
+    /**
+     * Whether this app is installed on the organization. A deliberate
+     * switch reads it so the install is raised before the switch takes
+     * effect, rather than leaving the reader acting somewhere the next call
+     * is refused.
+     */
+    installed: boolean;
+} | {
+    kind: 'needs-choice';
+} | {
+    kind: 'no-organization';
+};
+export interface ResolveDeps {
+    /** The open document's organization, where one is open. */
+    activeDocumentOrganizationId: () => Promise<string | null>;
+    /** An organization already resolved on this page load. */
+    cachedResolution: () => string | null;
+    /**
+     * The organization the launch named, where this page load carried one. A
+     * person clicking Open from an organization's dashboard has just said where
+     * they are working, so it outranks a carried choice and is never read as
+     * stale: an app the organization has not installed is what the install
+     * consent behind the refusal is for.
+     */
+    launchPreference: () => string | null;
+    /** The choice this tab carries for this app, from an earlier act. */
+    storedPreference: () => string | null;
+    fetchResolved: (prefer: string | null) => Promise<ResolveOutcome>;
+    /** The hosted dialog that asks the person; null when they dismissed it. */
+    pickOrganization: () => Promise<string | null>;
+    /**
+     * Drop the stored choice, for one the app can no longer act in. The server
+     * validates a preference against MEMBERSHIP, so a choice naming an
+     * organization the app has since been uninstalled from stays resolvable
+     * forever while serving nothing.
+     */
+    forgetPreference: () => void;
+    remember: (organizationId: string, 
+    /** Empty where the resolution carried an id and no name. */
+    organizationName: string, 
+    /**
+     * Whether to carry the choice past this page load. An organization this
+     * app is not installed on has not become one the app can act in yet: the
+     * act that resolved it is about to be refused, and the reader may decline
+     * the install that follows. Recording it anyway pins every later visit to
+     * an organization nothing they press can work in, with the chooser out of
+     * reach. It is persisted when the install lands instead.
+     */
+    persist: boolean) => void;
+}
+/**
+ * Which organization the next act uses.
+ *
+ * `ask: false` runs the same ladder and stops where it would raise the hosted
+ * chooser, answering null instead. That is what an app reading its own state
+ * before it acts needs: the question the chooser asks is one only the person
+ * can answer, and asking it unbidden takes the page over for something the
+ * reader never pressed.
+ */
+export declare function resolveActingOrganization(deps: ResolveDeps, options?: {
+    ask?: boolean;
+}): Promise<string | null>;
+/**
+ * What the chrome names: the organization the NEXT act would spend.
+ *
+ * An open document takes it over, because the document's organization is what
+ * every act made while it is open spends. That holds even when the name is
+ * unknown, which is a document in an organization this reader reaches through
+ * a directly shared project: the menu says nothing rather than naming the memo
+ * over it. Closing the document hands it back, so the two never disagree with
+ * what the app is about to do.
+ *
+ * Named whether or not the caller belongs to anywhere else. The menu offers a
+ * switch, and the surface behind it is also how a first or a second
+ * organization gets created, so what a caller with one has is a choice they
+ * have not made yet rather than no choice; naming the organization is what
+ * makes that switch legible instead of an offer to change something the menu
+ * never states.
+ *
+ * Null where neither is known, which is an ordinary state rather than a gap
+ * to fill: an app reached by its own URL, holding no document and nothing
+ * stored, has no organization until an act needs one, and resolving one to
+ * decorate a menu is exactly the boot-time question this design refuses.
+ */
+export declare function visibleOrganization(openDocument: {
+    organization: Named | null;
+} | null, memo: Named | null): {
+    id: string;
+    name: string;
+} | null;
+interface Named {
+    id: string;
+    name: string;
+}
+export interface ActingOrganizationFetchDeps {
+    apiBaseUrl: string;
+    getAccessToken: () => Promise<string | null>;
+    getAppAssertion: () => Promise<string | null>;
+    fetchImpl?: typeof fetch;
+}
+export declare function fetchActingOrganization(deps: ActingOrganizationFetchDeps, prefer: string | null): Promise<ResolveOutcome>;
+/**
+ * A deliberate switch, as the account menu drives it. Separate from
+ * `resolveActingOrganization` because the two differ in what follows the
+ * choice: a resolve is followed by the act that asked for it, which raises
+ * its own refusal, while a switch is followed by nothing at all. So the
+ * switch has to establish for itself that the app can act where the reader
+ * sent it, and has to tell the app that everything it read is now about a
+ * different organization.
+ */
+export interface SwitchDeps {
+    /** The organization being acted in now, so the surface can mark it. */
+    current: () => string | null;
+    pickOrganization: (current: string | undefined) => Promise<string | null>;
+    fetchResolved: (prefer: string) => Promise<ResolveOutcome>;
+    /** The hosted install dialog, pinned; null when the reader declined. */
+    offerInstall: (organizationId: string) => Promise<boolean>;
+    remember: (organizationId: string, organizationName: string) => void;
+    /** Re-reads the app under the new organization. */
+    reload: () => void;
+}
+export declare function switchActingOrganization(deps: SwitchDeps): Promise<boolean>;
+export {};
+//# sourceMappingURL=acting-organization.d.ts.map

package/dist/acting-organization.d.ts.map

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

package/dist/acting-organization.js

@@ -0,0 +1,278 @@
+// Which organization an act that has no document spends.
+//
+// An app opened from a dashboard is launched with one, and an app holding an
+// open document inherits that document's. Everything else is resolved by the
+// server from the caller's own context at the first act that needs it, so the
+// app is never handed a list and never asks at boot.
+//
+// The per-app sessionStorage slot below carries the answer forward within a
+// tab: keys are namespaced per app id so integrations on one origin don't
+// collide, and the slot is cleared on sign-out (session storage also drops on
+// tab close).
+import { applyAppAssertionHeader, applyClientVersionHeader } from './api-headers.js';
+import { BrassError } from './errors.js';
+const KEY_PREFIX = '__brass_acting_org_';
+// Single per-page-load warn: a resolve runs on every act that needs an
+// organization, so without the latch a server-rendered host would flood its
+// logs.
+let warnedUnavailable = false;
+function getStorage() {
+    if (typeof sessionStorage === 'undefined')
+        return null;
+    try {
+        return sessionStorage;
+    }
+    catch {
+        return null;
+    }
+}
+function warnOnceUnavailable() {
+    if (warnedUnavailable)
+        return;
+    warnedUnavailable = true;
+    console.warn('Brass: sessionStorage is unavailable, so the organization this app acts in is resolved again on every page load.');
+}
+function orgKey(appId) {
+    return `${KEY_PREFIX}${appId}`;
+}
+export function storeActingOrganization(appId, organizationId) {
+    const storage = getStorage();
+    if (!storage) {
+        warnOnceUnavailable();
+        return;
+    }
+    try {
+        storage.setItem(orgKey(appId), organizationId);
+    }
+    catch {
+        // Quota / disabled storage; drop silently. The stored value is a
+        // preference the server re-derives without it, so losing it costs a
+        // resolve rather than the act that needed one.
+    }
+}
+export function readActingOrganization(appId) {
+    const storage = getStorage();
+    let raw;
+    if (!storage)
+        return null;
+    try {
+        raw = storage.getItem(orgKey(appId));
+    }
+    catch {
+        // A storage that holds a handle but refuses reads (a partitioned or
+        // locked-down context). See `storeActingOrganization`.
+        return null;
+    }
+    const trimmed = raw?.trim() ?? '';
+    return trimmed === '' ? null : trimmed;
+}
+export function clearActingOrganization(appId) {
+    const storage = getStorage();
+    if (!storage)
+        return;
+    try {
+        storage.removeItem(orgKey(appId));
+    }
+    catch {
+        // See `storeActingOrganization`.
+    }
+}
+/**
+ * Which organization the next act uses.
+ *
+ * `ask: false` runs the same ladder and stops where it would raise the hosted
+ * chooser, answering null instead. That is what an app reading its own state
+ * before it acts needs: the question the chooser asks is one only the person
+ * can answer, and asking it unbidden takes the page over for something the
+ * reader never pressed.
+ */
+export async function resolveActingOrganization(deps, options = {}) {
+    const fromDocument = await deps.activeDocumentOrganizationId();
+    if (fromDocument) {
+        // Recorded, not merely returned. This is where the app is working, so it
+        // is what the next act spends once the document closes; without it a
+        // reader who opens a document, closes it and creates another is asked
+        // where to put the second one, having just worked in the answer. It carries no name (the
+        // document named an id) and does not reach the tab's slot: a document
+        // can live in an organization the reader reaches through a shared
+        // project and is not a member of, which is a place to act from while it
+        // is open rather than a choice to carry.
+        deps.remember(fromDocument, '', false);
+        return fromDocument;
+    }
+    const cached = deps.cachedResolution();
+    if (cached)
+        return cached;
+    // The stored choice is a preference rather than an answer: the server
+    // validates it against membership and ignores one that no longer holds, so
+    // a stale value self-heals into whatever the caller's context resolves to.
+    const launch = deps.launchPreference();
+    const stored = launch === null ? deps.storedPreference() : null;
+    const first = await deps.fetchResolved(launch ?? stored);
+    if (first.kind === 'resolved') {
+        // Membership is not the whole of what makes a choice usable. An
+        // organization the app has been uninstalled from still resolves, so a
+        // stored choice naming one would raise the install for a place somebody
+        // deliberately removed this app from, on every load, for as long as the
+        // tab lives. Read as stale instead: drop it and ask again with no
+        // preference, which reaches whatever this caller's context resolves to
+        // and otherwise the chooser, where the reader says where to work now.
+        //
+        // Only for a choice this tab was CARRYING. A launch, a resolution the
+        // reader just made, or their single membership is the answer either way,
+        // and the install is what it needs.
+        if (!first.installed && stored !== null && first.organizationId === stored) {
+            deps.forgetPreference();
+            const healed = await deps.fetchResolved(null);
+            if (healed.kind === 'resolved')
+                return keep(deps, healed);
+        }
+        else {
+            return keep(deps, first);
+        }
+    }
+    // Context could not answer. Only the person can, so a caller that asked not
+    // to raise a surface is told that rather than asked.
+    if (options.ask === false)
+        return null;
+    // The surface offers their own memberships and creates one where they have
+    // none, so the answer it gives is always one the server can resolve: asking
+    // twice would be asking the same question again rather than making progress.
+    const picked = await deps.pickOrganization();
+    if (!picked) {
+        throw new BrassError(first.kind === 'no-organization'
+            ? 'No organization yet. Create one to continue.'
+            : 'No organization chosen.', { status: 400 });
+    }
+    const second = await deps.fetchResolved(picked);
+    if (second.kind === 'resolved')
+        return keep(deps, second);
+    throw new BrassError('Brass could not use the organization you chose.', {
+        status: 400,
+    });
+}
+function keep(deps, outcome) {
+    deps.remember(outcome.organizationId, outcome.organizationName, outcome.installed);
+    return outcome.organizationId;
+}
+/**
+ * What the chrome names: the organization the NEXT act would spend.
+ *
+ * An open document takes it over, because the document's organization is what
+ * every act made while it is open spends. That holds even when the name is
+ * unknown, which is a document in an organization this reader reaches through
+ * a directly shared project: the menu says nothing rather than naming the memo
+ * over it. Closing the document hands it back, so the two never disagree with
+ * what the app is about to do.
+ *
+ * Named whether or not the caller belongs to anywhere else. The menu offers a
+ * switch, and the surface behind it is also how a first or a second
+ * organization gets created, so what a caller with one has is a choice they
+ * have not made yet rather than no choice; naming the organization is what
+ * makes that switch legible instead of an offer to change something the menu
+ * never states.
+ *
+ * Null where neither is known, which is an ordinary state rather than a gap
+ * to fill: an app reached by its own URL, holding no document and nothing
+ * stored, has no organization until an act needs one, and resolving one to
+ * decorate a menu is exactly the boot-time question this design refuses.
+ */
+export function visibleOrganization(openDocument, memo) {
+    // An open document takes the menu over ENTIRELY, naming its organization
+    // or nothing. Falling back to the memo here would be the exact fault this
+    // exists to prevent: the document's organization is what its acts spend,
+    // so a menu naming the memo over an open document names an organization
+    // the app is not using.
+    if (openDocument)
+        return named(openDocument.organization);
+    return named(memo);
+}
+function named(organization) {
+    // An id with no name is a resolution taken from an open document, which
+    // names no organization. There is nothing to draw until the chrome asks the
+    // server for one.
+    if (!organization || organization.name === '')
+        return null;
+    return { id: organization.id, name: organization.name };
+}
+// The refusals that are a question for the person rather than a fault: the
+// caller belongs to several organizations and none of the context named one,
+// or belongs to none at all.
+const OUTCOME_CODES = new Map([
+    ['destination_required', 'needs-choice'],
+    ['no_organization', 'no-organization'],
+]);
+export async function fetchActingOrganization(deps, prefer) {
+    const token = await deps.getAccessToken();
+    if (!token)
+        throw new BrassError('Not signed in', { status: 401 });
+    const headers = { authorization: `Bearer ${token}` };
+    applyClientVersionHeader(headers);
+    await applyAppAssertionHeader(headers, deps.getAppAssertion);
+    const base = deps.apiBaseUrl.replace(/\/$/, '');
+    const query = prefer ? `?prefer=${encodeURIComponent(prefer)}` : '';
+    const doFetch = deps.fetchImpl ?? fetch;
+    const response = await doFetch(`${base}/me/acting-organization${query}`, {
+        method: 'GET',
+        headers,
+    });
+    let body = {};
+    try {
+        body = (await response.json());
+    }
+    catch {
+        // Leaves the generic message below, which the status already qualifies.
+    }
+    if (response.ok && typeof body.organization_id === 'string') {
+        return {
+            kind: 'resolved',
+            organizationId: body.organization_id,
+            organizationName: typeof body.organization_name === 'string' ? body.organization_name : '',
+            // Absent reads as installed, so an older api that does not send it
+            // leaves the act to raise the refusal as it always did rather than
+            // asking for an install nothing established was missing.
+            installed: body.installed !== false,
+        };
+    }
+    const kind = typeof body.code === 'string' ? OUTCOME_CODES.get(body.code) : undefined;
+    if (response.status === 409 && kind)
+        return { kind };
+    throw new BrassError(typeof body.error === 'string' ? body.error : 'Could not resolve an organization', { status: response.status });
+}
+export async function switchActingOrganization(deps) {
+    const current = deps.current() ?? undefined;
+    const picked = await deps.pickOrganization(current);
+    if (!picked)
+        return false;
+    // Re-picking the organization the app is already acting in is a valid
+    // answer to the question the surface asks, and it moves nothing. The
+    // ordinary way to reach it is a caller with one organization opening the
+    // chooser to see what is there, so it must not cost them their open
+    // document and a page reload to say where they already are.
+    if (picked === current)
+        return false;
+    // The pick goes back to the server, which names the organization as the
+    // platform holds it and refuses one the caller cannot act in.
+    const named = await deps.fetchResolved(picked);
+    if (named.kind !== 'resolved')
+        return false;
+    // An organization this app is not installed on cannot serve it, so the
+    // install is asked for here rather than left to the next act. Without this
+    // the switch appears to succeed and the refusal arrives later, or on a
+    // reload, against work the reader has already started.
+    if (!named.installed && !(await deps.offerInstall(named.organizationId))) {
+        // Declining abandons the switch. Recording an organization the app cannot
+        // act in leaves the reader on one organization's screen with nothing they
+        // press able to work.
+        return false;
+    }
+    deps.remember(named.organizationId, named.organizationName);
+    // Everything the app read under the previous organization is about a
+    // different one now, and the app has no way to know which of its own state
+    // that covers. The reader asked for this, so re-reading the app is the
+    // expected consequence of their own act rather than a surprise, and the
+    // choice is already recorded so it survives.
+    deps.reload();
+    return true;
+}
+//# sourceMappingURL=acting-organization.js.map

package/dist/acting-organization.js.map

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

package/dist/api-headers.js

@@ -12,13 +12,13 @@ export async function applyAppAssertionHeader(headers, getAppAssertion) {
     if (assertion)
         headers['x-brass-app-assertion'] = assertion;
 }
-// Attaches the SDK's version as `x-brass-client` (`sdk/<version>`), the same
-// value reported on /refresh and the WS connect URL, so the server sees the
-// deployed SDK version at the data-API surface too. The minimum-version gate
-// reads it at document open to serve a too-old client an upgrade message
-// (rendered verbatim through `session.error`). Same boundary as the
-// app-assertion header: data API only, never a presigned URL. Unconditional, so the
-// version distribution covers read-only apps that never refresh.
+// Names the SDK and its version. Brass answers a build too old to serve with
+// an upgrade message, which reaches the app as `session.error` and is
+// rendered verbatim.
+//
+// Same boundary as the app-assertion header: Brass's own API calls carry it,
+// a presigned URL never does. Attached unconditionally, so an app that only
+// ever reads carries it too.
 export function applyClientVersionHeader(headers) {
     headers['x-brass-client'] = SDK_CLIENT_ID;
 }

package/dist/api-headers.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-headers.js","sourceRoot":"","sources":["../src/api-headers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,wEAAwE;AACxE,kDAAkD;AAClD,EAAE;AACF,uEAAuE;AACvE,mEAAmE;AACnE,uEAAuE;AACvE,yEAAyE;AACzE,QAAQ;AACR,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,OAA+B,EAC/B,eAA8C;IAE9C,MAAM,SAAS,GAAG,MAAM,eAAe,EAAE,EAAE,CAAC;IAC5C,IAAI,SAAS;QAAE,OAAO,CAAC,uBAAuB,CAAC,GAAG,SAAS,CAAC;AAC9D,CAAC;AAED,6EAA6E;AAC7E,4EAA4E;AAC5E,6EAA6E;AAC7E,yEAAyE;AACzE,oEAAoE;AACpE,oFAAoF;AACpF,iEAAiE;AACjE,MAAM,UAAU,wBAAwB,CAAC,OAA+B;IACtE,OAAO,CAAC,gBAAgB,CAAC,GAAG,aAAa,CAAC;AAC5C,CAAC"}
+{"version":3,"file":"api-headers.js","sourceRoot":"","sources":["../src/api-headers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,wEAAwE;AACxE,kDAAkD;AAClD,EAAE;AACF,uEAAuE;AACvE,mEAAmE;AACnE,uEAAuE;AACvE,yEAAyE;AACzE,QAAQ;AACR,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,OAA+B,EAC/B,eAA8C;IAE9C,MAAM,SAAS,GAAG,MAAM,eAAe,EAAE,EAAE,CAAC;IAC5C,IAAI,SAAS;QAAE,OAAO,CAAC,uBAAuB,CAAC,GAAG,SAAS,CAAC;AAC9D,CAAC;AAED,6EAA6E;AAC7E,sEAAsE;AACtE,qBAAqB;AACrB,EAAE;AACF,6EAA6E;AAC7E,4EAA4E;AAC5E,6BAA6B;AAC7B,MAAM,UAAU,wBAAwB,CAAC,OAA+B;IACtE,OAAO,CAAC,gBAAgB,CAAC,GAAG,aAAa,CAAC;AAC5C,CAAC"}

package/dist/call-service.d.ts

@@ -0,0 +1,74 @@
+export type CallServiceBody = string | Blob | FormData | URLSearchParams;
+export interface CallServiceOptions {
+    /** Defaults to `'POST'`. */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /**
+     * Sent to the service as-is, whatever a vendor asks for. The credential is
+     * not among them; Brass attaches that.
+     */
+    headers?: Record<string, string>;
+    body?: CallServiceBody;
+    /**
+     * Whether Brass asks the user for anything the call is missing: a
+     * credential at the host, consent to install the app in their
+     * organization, or which organization to act in. The call is sent again
+     * once they answer.
+     *
+     * Defaults to false, so the refusal comes back with its `code` for the
+     * app's own surface to answer, and `Brass.connectService(host)` opens the
+     * credential dialog when the reader asks for it.
+     */
+    requestMissingCredentials?: boolean;
+}
+export declare function encodeServiceHeaders(headers: Record<string, string>): string;
+export declare function normalizeServiceHost(host: string): string;
+export declare function brokeredCallUrl(apiBaseUrl: string, organizationId: string, host: string, path: string): string;
+export declare function invalidServicePath(path: string): boolean;
+export interface CallServiceDeps {
+    apiBaseUrl: string;
+    getAccessToken: () => Promise<string | null>;
+    getAppAssertion: () => Promise<string | null>;
+    /**
+     * Which organization this call uses, resolved from context. `ask` is true
+     * only where the caller asked for the missing pieces, and the resolve
+     * otherwise answers null for a page whose reader would have to be asked.
+     */
+    resolveOrganization: (ask: boolean) => Promise<string | null>;
+    /** Offers the hosted install dialog; true once an install landed. */
+    offerInstallConsent: (err: unknown) => Promise<boolean>;
+    /**
+     * Offers the hosted service-credential dialog for one host; true once that
+     * host became usable.
+     */
+    offerServiceCredential: (organizationId: string, host: string) => Promise<boolean>;
+    fetchImpl?: typeof fetch;
+}
+export declare function callService(deps: CallServiceDeps, host: string, path: string, options?: CallServiceOptions): Promise<Response>;
+export interface AppServiceState {
+    host: string;
+    /**
+     * The pattern your manifest declared, where it declared one
+     * (`*.myshopify.com`). One entry per tenant connected under it carries it,
+     * plus one naming the pattern itself while none is connected. Absent on a
+     * host declared literally.
+     */
+    declared_as?: string;
+    /**
+     * Whether `Brass.connectService(host)` can lead somewhere here. True where
+     * somebody using your app can supply what this host needs; false where it is
+     * waiting on the credential you enter as the app's author, which nobody on
+     * the page can settle.
+     */
+    connectable: boolean;
+    ready: boolean;
+    code?: string;
+    /**
+     * Values your manifest marked `readable`, for the account this call would
+     * spend. Use them to build a path the platform cannot build for you, such as
+     * the account id Cloudflare puts in every URL. Present only on a ready
+     * service, since only then is there an account to name.
+     */
+    values?: Record<string, string>;
+}
+export declare function listAppServices(deps: Pick<CallServiceDeps, 'apiBaseUrl' | 'getAccessToken' | 'getAppAssertion' | 'fetchImpl'>, organizationId: string): Promise<AppServiceState[]>;
+//# sourceMappingURL=call-service.d.ts.map

package/dist/call-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-service.d.ts","sourceRoot":"","sources":["../src/call-service.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,IAAI,GAAG,QAAQ,GAAG,eAAe,CAAC;AAEzE,MAAM,WAAW,kBAAkB;IACjC,4BAA4B;IAC5B,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACrD;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB;;;;;;;;;OASG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC;AAaD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAE5E;AAeD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,MAAM,CAKR;AAYD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAwBxD;AAgBD,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7C,eAAe,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9C;;;;OAIG;IACH,mBAAmB,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9D,qEAAqE;IACrE,mBAAmB,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACxD;;;OAGG;IACH,sBAAsB,EAAE,CACtB,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,MAAM,KACT,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,wBAAsB,WAAW,CAC/B,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,QAAQ,CAAC,CAgDnB;AA4DD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAMD,wBAAsB,eAAe,CACnC,IAAI,EAAE,IAAI,CACR,eAAe,EACf,YAAY,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,WAAW,CAClE,EACD,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,eAAe,EAAE,CAAC,CAkD5B"}