@nangohq/runner-sdk 0.70.8 → 0.71.0

package/dist/baseUrlOverrideDenylist.d.ts

@@ -1,19 +1,2 @@
-/**
- * Denylist helpers for runner-sdk sandbox code.
- *
- * Keep aligned with `packages/utils/lib/proxy/baseUrlOverrideDenylist.ts` (canonical for services).
- * runner-sdk cannot depend on other `@nangohq/*` packages, so this module is duplicated in-package.
- */
-export declare const DEFAULT_NANGO_PROXY_BASE_URL_OVERRIDE_DENYLIST: readonly ["169.254.169.254", "metadata.google.internal", "localhost", "127.0.0.1", "[::1]", "[::ffff:127.0.0.1]", "[::ffff:169.254.169.254]"];
-export declare function canonicalizeHostnameForDenylist(host: string): string;
-export declare function normalizeDenylistHost(entry: string): string;
-export declare function normalizeDenylist(denylist: string[] | undefined): Set<string>;
-export declare function isBaseUrlOverrideDenied(overrideUrl: string, denylist: Set<string>): boolean;
-export declare function mergeProxyBaseUrlOverrideDenylist(customEntries: string[]): string[];
-/**
- * Runner-side denylist resolution. Unlike server env parsing, runners always apply secure defaults
- * when the env is unset or empty (`[]` / `''`) so a server-level opt-out is not inherited.
- */
-export declare function resolveProxyBaseUrlOverrideDenylist(raw: string | undefined): string[];
+export { DEFAULT_NANGO_PROXY_BASE_URL_OVERRIDE_DENYLIST, canonicalizeHostnameForDenylist, isBaseUrlOverrideDenied, mergeProxyBaseUrlOverrideDenylist, normalizeDenylist, normalizeDenylistHost, resolveProxyBaseUrlOverrideDenylistForRunner as resolveProxyBaseUrlOverrideDenylist } from '@nangohq/egress';
 export declare function isBaseUrlOverridePolicyEnabledFromEnv(): boolean;
-export declare function getBaseUrlOverrideDenylistFromEnv(): Set<string>;

package/dist/baseUrlOverrideDenylist.js

@@ -1,76 +1,5 @@
-/**
- * Denylist helpers for runner-sdk sandbox code.
- *
- * Keep aligned with `packages/utils/lib/proxy/baseUrlOverrideDenylist.ts` (canonical for services).
- * runner-sdk cannot depend on other `@nangohq/*` packages, so this module is duplicated in-package.
- */
-export const DEFAULT_NANGO_PROXY_BASE_URL_OVERRIDE_DENYLIST = [
-    '169.254.169.254',
-    'metadata.google.internal',
-    'localhost',
-    '127.0.0.1',
-    '[::1]',
-    '[::ffff:127.0.0.1]',
-    '[::ffff:169.254.169.254]'
-];
-export function canonicalizeHostnameForDenylist(host) {
-    let h = host.trim().toLowerCase();
-    if (h.startsWith('[') && h.endsWith(']')) {
-        h = h.slice(1, -1);
-    }
-    while (h.endsWith('.')) {
-        h = h.slice(0, -1);
-    }
-    return h;
-}
-export function normalizeDenylistHost(entry) {
-    const trimmed = entry.trim();
-    if (!trimmed) {
-        return '';
-    }
-    let host;
-    if (trimmed.includes('://')) {
-        try {
-            host = new URL(trimmed).hostname;
-        }
-        catch {
-            host = trimmed;
-        }
-    }
-    else {
-        try {
-            host = new URL(`http://${trimmed}`).hostname;
-        }
-        catch {
-            host = trimmed;
-        }
-    }
-    return canonicalizeHostnameForDenylist(host);
-}
-export function normalizeDenylist(denylist) {
-    if (!denylist?.length) {
-        return new Set();
-    }
-    return new Set(denylist.map(normalizeDenylistHost).filter(Boolean));
-}
-export function isBaseUrlOverrideDenied(overrideUrl, denylist) {
-    if (denylist.size === 0) {
-        return false;
-    }
-    let hostname;
-    try {
-        hostname = canonicalizeHostnameForDenylist(new URL(overrideUrl).hostname);
-    }
-    catch {
-        return true;
-    }
-    return denylist.has(hostname);
-}
-export function mergeProxyBaseUrlOverrideDenylist(customEntries) {
-    const merged = [...DEFAULT_NANGO_PROXY_BASE_URL_OVERRIDE_DENYLIST, ...customEntries];
-    return [...new Set(merged)];
-}
-function isBaseUrlOverrideEnabledFromEnv() {
+export { DEFAULT_NANGO_PROXY_BASE_URL_OVERRIDE_DENYLIST, canonicalizeHostnameForDenylist, isBaseUrlOverrideDenied, mergeProxyBaseUrlOverrideDenylist, normalizeDenylist, normalizeDenylistHost, resolveProxyBaseUrlOverrideDenylistForRunner as resolveProxyBaseUrlOverrideDenylist } from '@nangohq/egress';
+export function isBaseUrlOverridePolicyEnabledFromEnv() {
     const raw = typeof process !== 'undefined' ? process.env['NANGO_PROXY_BASE_URL_OVERRIDE_ENABLED'] : undefined;
     if (raw === undefined) {
         return true;
@@ -78,55 +7,4 @@ function isBaseUrlOverrideEnabledFromEnv() {
     const normalized = raw.trim().toLowerCase();
     return normalized !== 'false' && normalized !== '0';
 }
-/**
- * Runner-side denylist resolution. Unlike server env parsing, runners always apply secure defaults
- * when the env is unset or empty (`[]` / `''`) so a server-level opt-out is not inherited.
- */
-export function resolveProxyBaseUrlOverrideDenylist(raw) {
-    if (raw === undefined) {
-        return [...DEFAULT_NANGO_PROXY_BASE_URL_OVERRIDE_DENYLIST];
-    }
-    const trimmed = raw.trim();
-    if (trimmed === '') {
-        return [...DEFAULT_NANGO_PROXY_BASE_URL_OVERRIDE_DENYLIST];
-    }
-    try {
-        const parsed = JSON.parse(trimmed);
-        if (!Array.isArray(parsed)) {
-            return [...DEFAULT_NANGO_PROXY_BASE_URL_OVERRIDE_DENYLIST];
-        }
-        if (parsed.length === 0) {
-            return [...DEFAULT_NANGO_PROXY_BASE_URL_OVERRIDE_DENYLIST];
-        }
-        const customEntries = parsed
-            .filter((v) => typeof v === 'string')
-            .map((v) => v.trim())
-            .filter(Boolean);
-        return mergeProxyBaseUrlOverrideDenylist(customEntries);
-    }
-    catch {
-        return [...DEFAULT_NANGO_PROXY_BASE_URL_OVERRIDE_DENYLIST];
-    }
-}
-let memoizedBaseUrlOverrideDenylist = null;
-export function isBaseUrlOverridePolicyEnabledFromEnv() {
-    return isBaseUrlOverrideEnabledFromEnv();
-}
-export function getBaseUrlOverrideDenylistFromEnv() {
-    if (memoizedBaseUrlOverrideDenylist) {
-        return memoizedBaseUrlOverrideDenylist;
-    }
-    const raw = typeof process !== 'undefined' ? process.env['NANGO_PROXY_BASE_URL_OVERRIDE_DENYLIST'] : undefined;
-    const entries = isBaseUrlOverrideEnabledFromEnv() ? resolveProxyBaseUrlOverrideDenylist(raw) : [...DEFAULT_NANGO_PROXY_BASE_URL_OVERRIDE_DENYLIST];
-    const denylist = normalizeDenylist(entries);
-    const lambdaRuntimeApi = typeof process !== 'undefined' ? process.env['AWS_LAMBDA_RUNTIME_API'] : undefined;
-    if (lambdaRuntimeApi) {
-        const normalized = normalizeDenylistHost(lambdaRuntimeApi);
-        if (normalized) {
-            denylist.add(normalized);
-        }
-    }
-    memoizedBaseUrlOverrideDenylist = denylist;
-    return memoizedBaseUrlOverrideDenylist;
-}
 //# sourceMappingURL=baseUrlOverrideDenylist.js.map

package/dist/baseUrlOverrideDenylist.js.map

@@ -1 +1 @@
-{"version":3,"file":"baseUrlOverrideDenylist.js","sourceRoot":"","sources":["../lib/baseUrlOverrideDenylist.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"baseUrlOverrideDenylist.js","sourceRoot":"","sources":["../lib/baseUrlOverrideDenylist.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,8CAA8C,EAC9C,+BAA+B,EAC/B,uBAAuB,EACvB,iCAAiC,EACjC,iBAAiB,EACjB,qBAAqB,EACrB,4CAA4C,IAAI,mCAAmC,EACtF,MAAM,iBAAiB,CAAC;AAEzB,MAAM,UAAU,qCAAqC;IACjD,MAAM,GAAG,GAAG,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,uCAAuC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9G,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC5C,OAAO,UAAU,KAAK,OAAO,IAAI,UAAU,KAAK,GAAG,CAAC;AACxD,CAAC"}

package/dist/function.d.ts

@@ -0,0 +1,259 @@
+import type { ProxyConfiguration } from './action.js';
+import type { ZodCheckpoint, ZodMetadata, ZodModel } from './types.js';
+import type { UncontrolledFetchOptions } from './uncontrolledFetch.js';
+import type { AllAuthCredentials, EnvironmentVariable, FunctionCapabilities, GetPublicConnection, GetPublicIntegration, HTTP_METHOD, MaybePromise, MergingStrategy, OnEventType, SdkLogger } from '@nangohq/types';
+import type * as z from 'zod';
+type InferZod<T> = T extends z.ZodTypeAny ? z.infer<T> : never;
+export type ConcurrencyLimit = 1 | 'max';
+/**
+ * Declares where the debounce/coalescing key is extracted from:
+ * - `{ body: '$.portalId' }`: dot notation path into the body
+ * - `{ header: 'x-goog-resource-id' }`: flat, case-insensitive header lookup
+ */
+export type DebounceKeySource = {
+    body: string;
+} | {
+    header: string;
+};
+export interface DebounceOptions {
+    keyBy?: DebounceKeySource | DebounceKeySource[];
+    windowMs: number;
+    maxEntities?: number;
+    take?: 'latest' | 'first' | 'all';
+}
+/**
+ * A trigger declares how a function is initiated FROM OUTSIDE; the `kind` discriminates what initiates execution.
+ * - `schedule`: a periodic schedule
+ * - `http`: an incoming http call or webhook request
+ * - `event`: an internal Nango lifecycle event
+ */
+export type TriggerDefinition = {
+    kind: 'schedule';
+    frequency: string;
+    autoStart?: boolean;
+} | {
+    kind: 'http';
+    subscriptions?: string[];
+    debounce?: DebounceOptions;
+} | {
+    kind: 'event';
+    events: OnEventType[];
+};
+export interface HttpRequest {
+    method: HTTP_METHOD;
+    path: string;
+    headers: Record<string, string>;
+    query: Record<string, string>;
+    body: unknown;
+}
+export interface CoalescedInfo {
+    count: number;
+    firstSeenAt: Date;
+    lastSeenAt: Date;
+}
+type HttpPayload<TT, TInput extends z.ZodTypeAny> = TT extends {
+    debounce: {
+        take: 'all';
+    };
+} ? z.infer<TInput>[] : z.infer<TInput>;
+interface TriggerBase {
+    /**
+     * Present when the run carries connection context (invoke calls may pass one;
+     * http/event may resolve one). Undefined for connection-less runs.
+     */
+    connection?: {
+        connection_id: string;
+        integrationId: string;
+    };
+}
+export type InvokeTrigger<TInput extends z.ZodTypeAny> = TriggerBase & {
+    kind: 'invoke';
+    input: z.infer<TInput>;
+};
+export type ScheduleTrigger = TriggerBase & {
+    kind: 'schedule';
+    input: null;
+};
+export type HttpTrigger<TT, TInput extends z.ZodTypeAny> = TriggerBase & {
+    kind: 'http';
+    input: HttpPayload<TT, TInput>;
+    request: HttpRequest;
+    subscriptions?: string[];
+    coalesced: CoalescedInfo;
+};
+export type EventTrigger = TriggerBase & {
+    kind: 'event';
+    input: {
+        event: OnEventType;
+    };
+};
+/**
+ * The runtime trigger a function `exec` receives. Any function can be invoked by another, but an
+ * invoke reuses the declared trigger's shape rather than adding a separate arrival — so `exec` only
+ * ever sees its declared kind and never has to discriminate. On the invoke path the runtime
+ * synthesizes the envelope (e.g. an http `request`/`coalesced` derived from the invoked input).
+ * A function with no declared trigger is invoke-only and receives `InvokeTrigger`.
+ */
+export type Trigger<TT extends TriggerDefinition | undefined, TInput extends z.ZodTypeAny> = TT extends {
+    kind: 'schedule';
+} ? ScheduleTrigger : TT extends {
+    kind: 'http';
+} ? HttpTrigger<TT, TInput> : TT extends {
+    kind: 'event';
+} ? EventTrigger : InvokeTrigger<TInput>;
+export interface NangoBase {
+    log(message: string, options?: unknown): Promise<void>;
+    setLogger(logger: SdkLogger): void;
+    getEnvironmentVariables(): Promise<EnvironmentVariable[] | null>;
+}
+export interface ConnectionCapability {
+    getConnection(): Promise<GetPublicConnection['Success']>;
+    getToken(): Promise<string | AllAuthCredentials>;
+    getIntegration(queries?: GetPublicIntegration['Querystring']): Promise<GetPublicIntegration['Success']['data']>;
+    getVariant(): string;
+}
+/**
+ * Present for connection-less runs instead of `getConnection`.
+ * Resolves the connection(s) an incoming event targets before fanning out work to them.
+ */
+export interface ConnectionSearchCapability {
+    searchConnections(filter: unknown): Promise<GetPublicConnection['Success'][]>;
+}
+/**
+ * Present when `requires.outbound` is not `false`:
+ * - outbound http via proxy
+ * - or direct fetch via `uncontrolledFetch`.
+ */
+export interface ProxyCapability {
+    proxy<T = unknown>(config: ProxyConfiguration): Promise<T>;
+    get<T = unknown>(config: Omit<ProxyConfiguration, 'method'>): Promise<T>;
+    post<T = unknown>(config: Omit<ProxyConfiguration, 'method'>): Promise<T>;
+    put<T = unknown>(config: Omit<ProxyConfiguration, 'method'>): Promise<T>;
+    patch<T = unknown>(config: Omit<ProxyConfiguration, 'method'>): Promise<T>;
+    delete<T = unknown>(config: Omit<ProxyConfiguration, 'method'>): Promise<T>;
+    paginate<T = unknown>(config: ProxyConfiguration): AsyncGenerator<T[]>;
+    uncontrolledFetch(options: UncontrolledFetchOptions): Promise<Response>;
+}
+export interface RecordCapability<TModels extends Record<string, ZodModel>> {
+    batchSave<K extends keyof TModels>(records: z.infer<TModels[K]>[], model: K): Promise<void>;
+    batchUpdate<K extends keyof TModels>(records: z.infer<TModels[K]>[], model: K): Promise<void>;
+    batchDelete<K extends keyof TModels>(records: z.infer<TModels[K]>[], model: K): Promise<void>;
+    setMergingStrategy(merging: MergingStrategy, model: keyof TModels): Promise<void>;
+    trackDeletesStart(model: keyof TModels): Promise<void>;
+    trackDeletesEnd(model: keyof TModels): Promise<void>;
+}
+export interface CheckpointCapability<TValue> {
+    getCheckpoint(): Promise<TValue | undefined>;
+    saveCheckpoint(checkpoint: TValue): Promise<void>;
+    clearCheckpoint(): Promise<void>;
+}
+export interface MetadataCapability<TValue> {
+    getMetadata(): Promise<TValue>;
+    setMetadata(metadata: TValue): Promise<void>;
+    updateMetadata(metadata: Partial<TValue>): Promise<void>;
+}
+type InferInput<T> = T extends CreateFunctionResponse<infer _M, infer I extends z.ZodTypeAny, infer _O, infer _Me, infer _Cp, infer _Tr, infer _R> ? z.infer<I> : void;
+type InferOutput<T> = T extends CreateFunctionResponse<infer _M, infer _I, infer O extends z.ZodTypeAny, infer _Me, infer _Cp, infer _Tr, infer _R> ? z.infer<O> : void;
+type InvokeConnection = {
+    connection_id: string;
+    integrationId: string;
+};
+type InvokeTarget = {
+    type: 'function';
+    capabilities: FunctionCapabilities;
+};
+type InvokeArgs<T> = [InferInput<T>] extends [void] ? [options?: {
+    connection?: InvokeConnection;
+}] : [options: {
+    input: InferInput<T>;
+    connection?: InvokeConnection;
+}];
+export interface InvokeCapability {
+    invoke<T extends InvokeTarget>(fn: T, ...args: InvokeArgs<T>): Promise<InferOutput<T>>;
+}
+export type Nango<TModels extends Record<string, ZodModel>, TMetadata extends ZodMetadata, TCheckpoint extends ZodCheckpoint, TRequires extends Requires> = TRequires extends {
+    connection: false;
+} ? NangoBase & ConnectionSearchCapability & (TRequires extends {
+    invoke: true;
+} ? InvokeCapability : unknown) : NangoBase & ConnectionCapability & (TRequires extends {
+    outbound: false;
+} ? unknown : ProxyCapability) & (TRequires extends {
+    invoke: true;
+} ? InvokeCapability : unknown) & ([keyof TModels] extends [never] ? unknown : RecordCapability<TModels>) & (TCheckpoint extends undefined ? unknown : CheckpointCapability<InferZod<TCheckpoint>>) & (TMetadata extends undefined ? unknown : MetadataCapability<InferZod<TMetadata>>);
+export type Requires = {
+    connection?: true;
+    outbound?: boolean;
+    invoke?: boolean;
+} | {
+    connection: false;
+    outbound?: false;
+    invoke?: boolean;
+};
+export interface CreateFunctionProps<TModels extends Record<string, ZodModel> = Record<never, ZodModel>, TInput extends z.ZodTypeAny = z.ZodVoid, TOutput extends z.ZodTypeAny = z.ZodVoid, TMetadata extends ZodMetadata = undefined, TCheckpoint extends ZodCheckpoint = undefined, TTrigger extends TriggerDefinition | undefined = undefined, TRequires extends Requires = {
+    outbound: true;
+    connection: true;
+}> {
+    description: string;
+    input?: TTrigger extends {
+        kind: 'schedule';
+    } | {
+        kind: 'event';
+    } ? never : TInput;
+    output?: TOutput;
+    data?: TRequires extends {
+        connection: false;
+    } ? never : {
+        models?: TModels;
+        metadata?: TMetadata;
+        checkpoint?: TCheckpoint;
+    };
+    trigger?: TTrigger;
+    requires?: TRequires;
+    limits?: {
+        concurrency?: {
+            perConnection?: TTrigger extends {
+                kind: 'schedule';
+            } ? 1 : ConcurrencyLimit;
+        };
+    };
+    exec: (nango: Nango<TModels, TMetadata, TCheckpoint, TRequires>, trigger: Trigger<TTrigger, TInput>) => MaybePromise<z.infer<TOutput>>;
+}
+export interface CreateFunctionResponse<TModels extends Record<string, ZodModel> = Record<never, ZodModel>, TInput extends z.ZodTypeAny = z.ZodVoid, TOutput extends z.ZodTypeAny = z.ZodVoid, TMetadata extends ZodMetadata = undefined, TCheckpoint extends ZodCheckpoint = undefined, TTrigger extends TriggerDefinition | undefined = undefined, TRequires extends Requires = {
+    outbound: true;
+    connection: true;
+}> extends CreateFunctionProps<TModels, TInput, TOutput, TMetadata, TCheckpoint, TTrigger, TRequires> {
+    type: 'function';
+    capabilities: FunctionCapabilities;
+}
+/**
+ * Create a function, a trigger-agnostic primitive with capabilities.
+ *
+ * @experimental **Not production ready.**
+ * The function primitive is under active development.
+ * Its API may change or be removed without notice, do NOT USE it in production integrations.
+ *
+ * @example
+ * ```ts
+ * export default createFunction({
+ *     description: 'Fetch issues from GitHub',
+ *     trigger: { kind: 'schedule', frequency: 'every hour' },
+ *     data: { models: { GithubIssue: z.object({ id: z.string() }) } },
+ *     exec: async (nango) => {
+ *         await nango.batchSave([{ id: '1' }], 'GithubIssue');
+ *     }
+ * });
+ * ```
+ */
+export declare function createFunction<TModels extends Record<string, ZodModel> = Record<never, ZodModel>, TInput extends z.ZodTypeAny = z.ZodVoid, TOutput extends z.ZodTypeAny = z.ZodVoid, TMetadata extends ZodMetadata = undefined, TCheckpoint extends ZodCheckpoint = undefined, TTrigger extends TriggerDefinition | undefined = undefined, TRequires extends Requires = {
+    outbound: true;
+    connection: true;
+}>(params: CreateFunctionProps<TModels, TInput, TOutput, TMetadata, TCheckpoint, TTrigger, TRequires>): CreateFunctionResponse<TModels, TInput, TOutput, TMetadata, TCheckpoint, TTrigger, TRequires>;
+export declare function deriveFunctionCapabilities(params: {
+    data?: {
+        models?: Record<string, ZodModel>;
+        metadata?: ZodMetadata;
+        checkpoint?: ZodCheckpoint;
+    } | undefined;
+    requires?: Requires | undefined;
+}): FunctionCapabilities;
+export {};

package/dist/function.js

@@ -0,0 +1,36 @@
+/**
+ * Create a function, a trigger-agnostic primitive with capabilities.
+ *
+ * @experimental **Not production ready.**
+ * The function primitive is under active development.
+ * Its API may change or be removed without notice, do NOT USE it in production integrations.
+ *
+ * @example
+ * ```ts
+ * export default createFunction({
+ *     description: 'Fetch issues from GitHub',
+ *     trigger: { kind: 'schedule', frequency: 'every hour' },
+ *     data: { models: { GithubIssue: z.object({ id: z.string() }) } },
+ *     exec: async (nango) => {
+ *         await nango.batchSave([{ id: '1' }], 'GithubIssue');
+ *     }
+ * });
+ * ```
+ */
+export function createFunction(params) {
+    return { type: 'function', ...params, capabilities: deriveFunctionCapabilities(params) };
+}
+// Derives the runtime capabilities from function definition
+export function deriveFunctionCapabilities(params) {
+    const models = params.data?.models;
+    // A connection-less function has no connection to proxy through, so outbound is always off.
+    const connectionLess = params.requires?.connection === false;
+    return {
+        usesRecords: !!models && Object.keys(models).length > 0,
+        usesCheckpoints: !!params.data?.checkpoint,
+        usesMetadata: !!params.data?.metadata,
+        usesOutbound: !connectionLess && params.requires?.outbound !== false,
+        usesInvoke: params.requires?.invoke === true
+    };
+}
+//# sourceMappingURL=function.js.map

package/dist/function.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"function.js","sourceRoot":"","sources":["../lib/function.ts"],"names":[],"mappings":"AA8QA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,cAAc,CAS1B,MAAkG;IAElG,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,MAAM,EAAE,YAAY,EAAE,0BAA0B,CAAC,MAAM,CAAC,EAAE,CAAC;AAC7F,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,0BAA0B,CAAC,MAG1C;IACG,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC;IACnC,4FAA4F;IAC5F,MAAM,cAAc,GAAG,MAAM,CAAC,QAAQ,EAAE,UAAU,KAAK,KAAK,CAAC;IAC7D,OAAO;QACH,WAAW,EAAE,CAAC,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC;QACvD,eAAe,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,UAAU;QAC1C,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ;QACrC,YAAY,EAAE,CAAC,cAAc,IAAI,MAAM,CAAC,QAAQ,EAAE,QAAQ,KAAK,KAAK;QACpE,UAAU,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI;KAC/C,CAAC;AACN,CAAC"}