@choiceapps/communityservices-sdk 0.1.0

package/browser/ui-login.mjs

@@ -0,0 +1,135 @@
+import {resolveUiConnection} from './connection.mjs';
+import {readFile} from 'node:fs/promises';
+import {parseEnv} from 'node:util';
+import {createHash} from 'node:crypto';
+import {homedir} from 'node:os';
+import {join} from 'node:path';
+import {createFileGwtMutationStore} from './file-store.mjs';
+import {attachAuthentication} from './session-authentication.mjs';
+import {withPageLock} from './page-lock.mjs';
+import {waitForLogin,submitExpiredPassword,restoreOriginalPassword,probeAuthentication} from './password-recovery.mjs';
+
+export class LoginError extends Error {
+ constructor(code,stage,recoveryStage){
+  const detail=code==='PASSWORD_EXPIRED'?'Password expired; passwordRecovery is disabled':code==='RECOVERY_UNCERTAIN'?'Password recovery requires reconciliation; no uncertain password change was replayed':code==='RECOVERY_CONFIGURATION'?'Invalid password recovery configuration or journal':'Headless authentication failed; no automatic credential retry was performed';
+  super(`Login: ${detail} (stage: ${stage}${recoveryStage?', recovery: '+recoveryStage:''})`);
+  this.name='LoginError';this.code=code;this.stage=stage;this.recoveryStage=recoveryStage;
+ }
+}
+const stages=new Set(['temporary-attempted','temporary-active','temporary-verification-attempted','restore-attempted','restored','original-verification-attempted','original-verified']);
+
+/** Fresh headless application context. Recovery defaults on and never retries an uncertain password write.
+ * Credentials stay in memory; the original .env is unchanged. Share the recovery store across callers. */
+export async function openUiSession(options) {
+ const connection=resolveUiConnection(options);
+ options={...options,...connection};
+ const session=await loginUiSession(options);
+ const auth=attachAuthentication(session.page,async()=>{
+  const refreshed=await loginUiSession(options,session);
+  session.passwordRecovery=refreshed.passwordRecovery;
+ },()=>probeAuthentication(session.context,connection.moduleBaseUrl,Math.min(options.timeoutMs??90000,15000)),connection);
+ const close=session.close;
+ session.ensureAuthenticated=()=>withPageLock(session.page,async()=>{});
+ session.reauthenticate=()=>withPageLock(session.page,()=>auth.reauthenticate(),{authentication:false});
+ session.close=()=>withPageLock(session.page,async()=>{auth.close();await close();},{authentication:false});
+ return session;
+}
+async function loginUiSession({chromium,tenant,moduleBaseUrl,envFile='.env',executablePath,timeoutMs=90000,passwordRecovery},existing) {
+ const connection=resolveUiConnection({tenant,moduleBaseUrl}),target=new URL(connection.moduleBaseUrl);
+ let browser=existing?.browser,stage='credentials',record,usedExisting=false;
+ const extraContexts=[];
+ const failure=code=>new LoginError(code,stage,record?.stage);
+ try {
+  const env=parseEnv(await readFile(envFile,'utf8'));
+  if(!env.HMIS_UI_USER||!env.HMIS_UI_PASSWORD)throw failure('LOGIN_FAILED');
+  const recovery=passwordRecovery!==false,appendCharacter=passwordRecovery?.appendCharacter??'!';
+  if(passwordRecovery!==undefined&&passwordRecovery!==false&&(!passwordRecovery||typeof passwordRecovery!=='object'||Array.isArray(passwordRecovery)))throw failure('RECOVERY_CONFIGURATION');
+  const store=passwordRecovery?.store??createFileGwtMutationStore(env.HMIS_UI_PASSWORD_RECOVERY_DIR||join(homedir(),'.wellsky-sdk','password-recovery'));
+  if(recovery&&(!store||!['withLock','read','write'].every(k=>typeof store[k]==='function')||typeof appendCharacter!=='string'||!/^[!-~]$/.test(appendCharacter)))throw failure('RECOVERY_CONFIGURATION');
+  const accountHash=createHash('sha256').update(env.HMIS_UI_USER.trim().toLowerCase()).digest('hex');
+  const scope=JSON.stringify([connection.scope,'password-recovery',accountHash]);
+  const run=async()=>{
+   let records=[];
+   if(recovery){
+    records=await store.read(scope);
+    if(!Array.isArray(records)||records.some((r,i)=>!r||r.version!==1||!stages.has(r.stage)||typeof r.appendCharacter!=='string'||!/^[!-~]$/.test(r.appendCharacter)||i<records.length-1&&r.stage!=='original-verified'))throw failure('RECOVERY_CONFIGURATION');
+    record=records.at(-1);
+    if(record?.stage==='original-verified')record=undefined;
+    if(record&&(env.HMIS_UI_PASSWORD.length<8||env.HMIS_UI_PASSWORD.length>=50))throw failure('RECOVERY_CONFIGURATION');
+    if(record&&record.appendCharacter!==appendCharacter)throw failure('RECOVERY_CONFIGURATION');
+    if(record&&['temporary-verification-attempted','original-verification-attempted'].includes(record.stage))throw failure('RECOVERY_UNCERTAIN');
+   }
+   const persist=async value=>{record.stage=value;await store.write(scope,structuredClone(records));};
+   stage='launch';browser??=await chromium.launch({headless:true,chromiumSandbox:true,...(executablePath?{executablePath}:{})});
+   const login=async(password,fresh=false)=>{
+    const reuse=existing&&!usedExisting&&!fresh;
+    if(reuse){usedExisting=true;await existing.context.clearCookies();}
+    const context=reuse?existing.context:await browser.newContext({viewport:{width:1280,height:900}});
+    if(existing&&!reuse)extraContexts.push(context);
+    if(!reuse)await context.route('**/*',async route=>{
+     const request=route.request(),url=new URL(request.url());
+     if((request.isNavigationRequest()||!['GET','HEAD','OPTIONS'].includes(request.method()))&&(url.origin!==target.origin||!url.pathname.startsWith('/'+tenant+'/')))return route.abort();
+     return route.continue();
+    });
+    const page=reuse?existing.page:await context.newPage();page.setDefaultTimeout(timeoutMs);
+    stage='open-application';await page.goto(connection.moduleBaseUrl+'index.html',{waitUntil:'domcontentloaded',timeout:timeoutMs});
+    await page.locator('[id="formfield-login"]').fill(env.HMIS_UI_USER);
+    await page.locator('[id="formfield-password"]').fill(password);
+    stage='login';await page.locator('[id="LoginView.fbtn_submit"]').click();
+    const outcome=await waitForLogin(page,timeoutMs);
+    return {context,page,outcome};
+   };
+   const finish=async(session,recovered)=>{
+    if(existing&&session.page!==existing.page){
+     // Transfer only this configured origin's verified cookies in memory. Keep the Page identity
+     // used by existing adapters, including servers that replace the earlier login session.
+     const cookies=await session.context.cookies(connection.moduleBaseUrl);
+     await existing.context.clearCookies();await existing.context.addCookies(cookies);
+     await session.context.close();
+     await existing.page.goto(connection.moduleBaseUrl+'index.html',{waitUntil:'domcontentloaded',timeout:timeoutMs});
+     if(await waitForLogin(existing.page,timeoutMs)!=='dashboard')throw failure('RECOVERY_UNCERTAIN');
+     session=existing;
+    }
+    return {connection,browser,context:session.context,page:session.page,passwordRecovery:recovered?'restored-original':'not-needed',close:()=>browser.close()};
+   };
+   const temporary=env.HMIS_UI_PASSWORD+appendCharacter;
+   // A lost save acknowledgement permits one authentication probe, never another save.
+   if(record&&['restore-attempted','restored'].includes(record.stage)){
+    await persist('original-verification-attempted');
+    const session=await login(env.HMIS_UI_PASSWORD);
+    if(session.outcome!=='dashboard')throw failure('RECOVERY_UNCERTAIN');
+    await persist('original-verified');return finish(session,true);
+   }
+   const resuming=!!record;
+   if(resuming)await persist('temporary-verification-attempted');
+   let session=await login(resuming?temporary:env.HMIS_UI_PASSWORD);
+   if(resuming){
+    if(session.outcome!=='dashboard')throw failure('RECOVERY_UNCERTAIN');
+    await persist('temporary-active');
+   }else if(session.outcome==='dashboard')return finish(session,false);
+   else{
+    if(!recovery)throw failure('PASSWORD_EXPIRED');
+    if(env.HMIS_UI_PASSWORD.length<8||env.HMIS_UI_PASSWORD.length>=50)throw failure('RECOVERY_CONFIGURATION');
+    record={version:1,appendCharacter,stage:'temporary-attempted'};records.push(record);
+    stage='temporary-password';
+    await submitExpiredPassword(session.page,temporary,()=>persist('temporary-attempted'),timeoutMs);
+    await persist('temporary-active');
+   }
+   stage='restore-original';
+   await restoreOriginalPassword(session.page,temporary,env.HMIS_UI_PASSWORD,()=>persist('restore-attempted'),timeoutMs);
+   await persist('restored');
+   if(!existing)await session.context.close();
+   await persist('original-verification-attempted');
+   session=await login(env.HMIS_UI_PASSWORD,true);
+   if(session.outcome!=='dashboard')throw failure('RECOVERY_UNCERTAIN');
+   await persist('original-verified');return finish(session,true);
+  };
+  return recovery?await store.withLock(scope,run):await run();
+ }catch(error){
+  if(!existing)await browser?.close().catch(()=>{});
+  else await Promise.allSettled(extraContexts.map(context=>context.close()));
+  if(error instanceof LoginError)throw error;
+  // Playwright errors can include fill arguments. Never propagate their message or cause.
+  throw failure(record&&record.stage!=='original-verified'?'RECOVERY_UNCERTAIN':'LOGIN_FAILED');
+ }
+}

package/dist/cjs/bulk.d.ts

@@ -0,0 +1,33 @@
+import { WellSkyError } from "./runtime.js";
+export type BulkItemResult<T> = {
+    index: number;
+    outcome: "fulfilled";
+    value: T;
+} | {
+    index: number;
+    outcome: "rejected";
+    error: WellSkyError;
+} | {
+    index: number;
+    outcome: "skipped";
+    reason: "cancelled" | "callback_failed";
+};
+export interface BulkReport<T> {
+    results: BulkItemResult<T>[];
+    callbackErrors: {
+        index: number;
+        error: WellSkyError;
+    }[];
+}
+export interface BulkOptions<T> {
+    concurrency?: number;
+    signal?: AbortSignal;
+    /** Called as each item completes. Awaited before scheduling the next item on that worker. */
+    onResult?: (result: BulkItemResult<T>) => void | Promise<void>;
+}
+/** No item is retried here. A rejected write promise does not prove the write was rolled back. */
+export declare function mapBulk<I, O>(items: readonly I[], worker: (item: I, context: {
+    index: number;
+    signal?: AbortSignal;
+}) => Promise<O>, options?: BulkOptions<O>): Promise<BulkReport<O>>;
+//# sourceMappingURL=bulk.d.ts.map

package/dist/cjs/bulk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulk.d.ts","sourceRoot":"","sources":["../../src/bulk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,MAAM,MAAM,cAAc,CAAC,CAAC,IACxB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACjD;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GAC3D;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,iBAAiB,CAAA;CAAE,CAAC;AACnF,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7B,cAAc,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,YAAY,CAAA;KAAE,EAAE,CAAC;CAC1D;AACD,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChE;AAED,kGAAkG;AAClG,wBAAsB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,WAAW,CAAC,CAAC,CAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CA0BhM"}

package/dist/cjs/bulk.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapBulk = mapBulk;
+const runtime_js_1 = require("./runtime.js");
+const errors_js_1 = require("./errors.js");
+/** No item is retried here. A rejected write promise does not prove the write was rolled back. */
+async function mapBulk(items, worker, options = {}) {
+    const concurrency = options.concurrency ?? 8;
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1)
+        throw new errors_js_1.ValidationError("bulk configuration", ["concurrency"]);
+    const results = [];
+    const callbackErrors = [];
+    let next = 0;
+    let callbackFailed = false;
+    const jobs = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+        while (next < items.length && !options.signal?.aborted && !callbackFailed) {
+            const index = next++;
+            // The index is reserved synchronously and is bounded by items.length.
+            const item = items[index];
+            let result;
+            try {
+                result = { index, outcome: "fulfilled", value: await worker(item, { index, ...(options.signal ? { signal: options.signal } : {}) }) };
+            }
+            catch (error) {
+                result = { index, outcome: "rejected", error: error instanceof runtime_js_1.WellSkyError ? error : new runtime_js_1.WellSkyError("protocol", "bulk item") };
+            }
+            results[index] = result;
+            try {
+                await options.onResult?.(result);
+            }
+            catch {
+                callbackFailed = true;
+                callbackErrors.push({ index, error: new runtime_js_1.WellSkyError("protocol", "bulk result callback") });
+            }
+        }
+    });
+    await Promise.all(jobs);
+    for (let index = next; index < items.length; index++)
+        results[index] = { index, outcome: "skipped", reason: callbackFailed ? "callback_failed" : "cancelled" };
+    return { results, callbackErrors };
+}
+//# sourceMappingURL=bulk.js.map

package/dist/cjs/bulk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulk.js","sourceRoot":"","sources":["../../src/bulk.ts"],"names":[],"mappings":";;AAmBA,0BA0BC;AA7CD,6CAA4C;AAC5C,2CAA8C;AAiB9C,kGAAkG;AAC3F,KAAK,UAAU,OAAO,CAAO,KAAmB,EAAE,MAAiF,EAAE,UAA0B,EAAE;IACtK,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,WAAW,GAAG,CAAC;QAAE,MAAM,IAAI,2BAAe,CAAC,oBAAoB,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC;IAC5H,MAAM,OAAO,GAAwB,EAAE,CAAC;IACxC,MAAM,cAAc,GAAoC,EAAE,CAAC;IAC3D,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,cAAc,GAAG,KAAK,CAAC;IAC3B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,IAAI,EAAE;QAClF,OAAO,IAAI,GAAG,KAAK,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC,cAAc,EAAE,CAAC;YAC1E,MAAM,KAAK,GAAG,IAAI,EAAE,CAAC;YACrB,sEAAsE;YACtE,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAM,CAAC;YAC/B,IAAI,MAAyB,CAAC;YAC9B,IAAI,CAAC;gBAAC,MAAM,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;YAAC,CAAC;YAC9I,OAAO,KAAK,EAAE,CAAC;gBAAC,MAAM,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,YAAY,yBAAY,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,yBAAY,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,CAAC;YAAC,CAAC;YACpJ,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC;YACxB,IAAI,CAAC;gBAAC,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAC;YAAC,CAAC;YACzC,MAAM,CAAC;gBACL,cAAc,GAAG,IAAI,CAAC;gBACtB,cAAc,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,yBAAY,CAAC,UAAU,EAAE,sBAAsB,CAAC,EAAE,CAAC,CAAC;YAC9F,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IACH,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACxB,KAAK,IAAI,KAAK,GAAG,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE;QAAE,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IAC/J,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;AACrC,CAAC","sourcesContent":["import { WellSkyError } from \"./runtime.js\";\nimport { ValidationError } from \"./errors.js\";\n\nexport type BulkItemResult<T> =\n  | { index: number; outcome: \"fulfilled\"; value: T }\n  | { index: number; outcome: \"rejected\"; error: WellSkyError }\n  | { index: number; outcome: \"skipped\"; reason: \"cancelled\" | \"callback_failed\" };\nexport interface BulkReport<T> {\n  results: BulkItemResult<T>[];\n  callbackErrors: { index: number; error: WellSkyError }[];\n}\nexport interface BulkOptions<T> {\n  concurrency?: number;\n  signal?: AbortSignal;\n  /** Called as each item completes. Awaited before scheduling the next item on that worker. */\n  onResult?: (result: BulkItemResult<T>) => void | Promise<void>;\n}\n\n/** No item is retried here. A rejected write promise does not prove the write was rolled back. */\nexport async function mapBulk<I, O>(items: readonly I[], worker: (item: I, context: { index: number; signal?: AbortSignal }) => Promise<O>, options: BulkOptions<O> = {}): Promise<BulkReport<O>> {\n  const concurrency = options.concurrency ?? 8;\n  if (!Number.isSafeInteger(concurrency) || concurrency < 1) throw new ValidationError(\"bulk configuration\", [\"concurrency\"]);\n  const results: BulkItemResult<O>[] = [];\n  const callbackErrors: BulkReport<O>[\"callbackErrors\"] = [];\n  let next = 0;\n  let callbackFailed = false;\n  const jobs = Array.from({ length: Math.min(concurrency, items.length) }, async () => {\n    while (next < items.length && !options.signal?.aborted && !callbackFailed) {\n      const index = next++;\n      // The index is reserved synchronously and is bounded by items.length.\n      const item = items[index] as I;\n      let result: BulkItemResult<O>;\n      try { result = { index, outcome: \"fulfilled\", value: await worker(item, { index, ...(options.signal ? { signal: options.signal } : {}) }) }; }\n      catch (error) { result = { index, outcome: \"rejected\", error: error instanceof WellSkyError ? error : new WellSkyError(\"protocol\", \"bulk item\") }; }\n      results[index] = result;\n      try { await options.onResult?.(result); }\n      catch {\n        callbackFailed = true;\n        callbackErrors.push({ index, error: new WellSkyError(\"protocol\", \"bulk result callback\") });\n      }\n    }\n  });\n  await Promise.all(jobs);\n  for (let index = next; index < items.length; index++) results[index] = { index, outcome: \"skipped\", reason: callbackFailed ? \"callback_failed\" : \"cancelled\" };\n  return { results, callbackErrors };\n}\n"]}

package/dist/cjs/control.d.ts

@@ -0,0 +1,35 @@
+import type { ClientEvent, ClientHealth, ClientOptions } from "./runtime.js";
+export declare class Semaphore {
+    #private;
+    active: number;
+    constructor(capacity: number);
+    get queued(): number;
+    acquire(signal: AbortSignal, operation: string): Promise<() => void>;
+}
+export interface SharedAuthentication {
+    cached?: {
+        token: string;
+        expiresAt: number;
+    } | undefined;
+    inFlight?: Promise<string> | undefined;
+}
+export declare function identity(value: object): number;
+/** Credentials are hashed for cache identity and never exposed in keys or diagnostics. */
+export declare function sharedAuthentication(scope: string, auth: ClientOptions["auth"]): Promise<SharedAuthentication>;
+export declare const tokenMintQueue: Semaphore;
+export declare class RequestControl {
+    #private;
+    readonly semaphore: Semaphore;
+    tokenMintCount: number;
+    constructor(concurrency: number, settings: {
+        threshold: number;
+        windowMs: number;
+        durationMs: number;
+    });
+    check(operation: string): void;
+    failed(status: number): number | undefined;
+    health(): ClientHealth;
+}
+export declare function requestControl(scope: string, options: ClientOptions): RequestControl;
+export declare function emit(options: Pick<ClientOptions, "hooks" | "logger">, event: ClientEvent): void;
+//# sourceMappingURL=control.d.ts.map

package/dist/cjs/control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../../src/control.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAI7E,qBAAa,SAAS;;IACpB,MAAM,SAAK;gBAGC,QAAQ,EAAE,MAAM;IAC5B,IAAI,MAAM,IAAI,MAAM,CAA+B;IACnD,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;CAuBrE;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAC1D,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;CACxC;AAGD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI9C;AAED,0FAA0F;AAC1F,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,oBAAoB,CAAC,CASpH;AACD,eAAO,MAAM,cAAc,WAAmB,CAAC;AAE/C,qBAAa,cAAc;;IACzB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAI9B,cAAc,SAAK;gBACP,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;IAItG,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI9B,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAQ1C,MAAM,IAAI,YAAY;CAGvB;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,cAAc,CASpF;AAED,wBAAgB,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,OAAO,GAAG,QAAQ,CAAC,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAO/F"}

package/dist/cjs/control.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestControl = exports.tokenMintQueue = exports.Semaphore = void 0;
+exports.identity = identity;
+exports.sharedAuthentication = sharedAuthentication;
+exports.requestControl = requestControl;
+exports.emit = emit;
+const runtime_js_1 = require("./runtime.js");
+const errors_js_1 = require("./errors.js");
+class Semaphore {
+    active = 0;
+    #capacity;
+    #queue = [];
+    constructor(capacity) { this.#capacity = capacity; }
+    get queued() { return this.#queue.length; }
+    acquire(signal, operation) {
+        return new Promise((resolve, reject) => {
+            let released = false;
+            const grant = () => {
+                signal.removeEventListener("abort", abort);
+                this.active++;
+                resolve(() => {
+                    if (released)
+                        return;
+                    released = true;
+                    this.active--;
+                    this.#queue.shift()?.grant();
+                });
+            };
+            const abort = () => {
+                const index = this.#queue.indexOf(waiter);
+                if (index >= 0)
+                    this.#queue.splice(index, 1);
+                reject(new runtime_js_1.WellSkyError(signal.reason instanceof DOMException && signal.reason.name === "TimeoutError" ? "timeout" : "aborted", operation));
+            };
+            const waiter = { grant, signal, abort };
+            if (signal.aborted) {
+                abort();
+                return;
+            }
+            if (this.active < this.#capacity)
+                grant();
+            else {
+                this.#queue.push(waiter);
+                signal.addEventListener("abort", abort, { once: true });
+            }
+        });
+    }
+}
+exports.Semaphore = Semaphore;
+const identities = new WeakMap();
+let nextIdentity = 1;
+function identity(value) {
+    const prior = identities.get(value);
+    if (prior !== undefined)
+        return prior;
+    const id = nextIdentity++;
+    identities.set(value, id);
+    return id;
+}
+const authentication = new Map();
+/** Credentials are hashed for cache identity and never exposed in keys or diagnostics. */
+async function sharedAuthentication(scope, auth) {
+    const descriptor = auth.kind === "credentials" ? [scope, auth.kind, auth.username, auth.password] : auth.kind === "provider" ? [scope, auth.kind, identity(auth.getToken)] : [scope, auth.kind];
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify(descriptor)));
+    const key = Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, "0")).join("");
+    const prior = authentication.get(key);
+    if (prior)
+        return prior;
+    const state = {};
+    authentication.set(key, state);
+    return state;
+}
+exports.tokenMintQueue = new Semaphore(1);
+class RequestControl {
+    semaphore;
+    #settings;
+    #failures = [];
+    #until = 0;
+    tokenMintCount = 0;
+    constructor(concurrency, settings) {
+        for (const value of [concurrency, settings.threshold, settings.windowMs, settings.durationMs])
+            if (!Number.isSafeInteger(value) || value < 1)
+                throw new TypeError("Concurrency and cooldown settings must be positive integers");
+        this.semaphore = new Semaphore(concurrency);
+        this.#settings = { ...settings };
+    }
+    check(operation) {
+        if (this.#until > Date.now())
+            throw new errors_js_1.CooldownError(operation, this.#until);
+        if (this.#until !== 0) {
+            this.#until = 0;
+            this.#failures = [];
+        }
+    }
+    failed(status) {
+        if (status !== 401 && status !== 403 && status !== 429 && status < 500)
+            return undefined;
+        const now = Date.now();
+        this.#failures = this.#failures.filter(time => time > now - this.#settings.windowMs);
+        this.#failures.push(now);
+        if (this.#failures.length >= this.#settings.threshold && this.#until <= now) {
+            this.#until = now + this.#settings.durationMs;
+            return this.#until;
+        }
+        return undefined;
+    }
+    health() {
+        return { state: this.#until > Date.now() ? "open" : "closed", until: this.#until > Date.now() ? new Date(this.#until).toISOString() : null, activeRequests: this.semaphore.active, queuedRequests: this.semaphore.queued, tokenMintCount: this.tokenMintCount };
+    }
+}
+exports.RequestControl = RequestControl;
+const controls = new Map();
+function requestControl(scope, options) {
+    const concurrency = options.maxConcurrency ?? 8;
+    const cooldown = options.cooldown ?? { threshold: 5, windowMs: 10_000, durationMs: 30_000 };
+    const signature = JSON.stringify([concurrency, cooldown.threshold, cooldown.windowMs, cooldown.durationMs]);
+    const existing = controls.get(scope);
+    if (existing && existing.signature !== signature)
+        throw new TypeError("Clients sharing a tenant and transport must use the same concurrency/cooldown settings");
+    if (existing)
+        return existing.value;
+    const value = new RequestControl(concurrency, cooldown);
+    controls.set(scope, { signature, value });
+    return value;
+}
+function emit(options, event) {
+    const hooks = options.hooks;
+    const handler = event.type === "request" ? hooks?.onRequest : event.type === "response" ? hooks?.onResponse : event.type === "tokenMint" ? hooks?.onTokenMint : event.type === "throttle" ? hooks?.onThrottle : hooks?.onCooldown;
+    const safe = Object.freeze({ ...event });
+    // Observers must not turn a completed write into a thrown error or a replay.
+    try {
+        void Promise.resolve(handler?.(safe)).catch(() => { });
+    }
+    catch { /* Observer failures cannot change request outcomes. */ }
+    try {
+        void Promise.resolve(options.logger?.(safe)).catch(() => { });
+    }
+    catch { /* Same boundary for user-supplied loggers. */ }
+}
+//# sourceMappingURL=control.js.map

package/dist/cjs/control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.js","sourceRoot":"","sources":["../../src/control.ts"],"names":[],"mappings":"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","sourcesContent":["import { WellSkyError } from \"./runtime.js\";\nimport type { ClientEvent, ClientHealth, ClientOptions } from \"./runtime.js\";\nimport { CooldownError } from \"./errors.js\";\n\ninterface Waiter { grant: () => void; signal: AbortSignal; abort: () => void }\nexport class Semaphore {\n  active = 0;\n  readonly #capacity: number;\n  readonly #queue: Waiter[] = [];\n  constructor(capacity: number) { this.#capacity = capacity; }\n  get queued(): number { return this.#queue.length; }\n  acquire(signal: AbortSignal, operation: string): Promise<() => void> {\n    return new Promise((resolve, reject) => {\n      let released = false;\n      const grant = () => {\n        signal.removeEventListener(\"abort\", abort);\n        this.active++;\n        resolve(() => {\n          if (released) return;\n          released = true; this.active--;\n          this.#queue.shift()?.grant();\n        });\n      };\n      const abort = () => {\n        const index = this.#queue.indexOf(waiter);\n        if (index >= 0) this.#queue.splice(index, 1);\n        reject(new WellSkyError(signal.reason instanceof DOMException && signal.reason.name === \"TimeoutError\" ? \"timeout\" : \"aborted\", operation));\n      };\n      const waiter: Waiter = { grant, signal, abort };\n      if (signal.aborted) { abort(); return; }\n      if (this.active < this.#capacity) grant();\n      else { this.#queue.push(waiter); signal.addEventListener(\"abort\", abort, { once: true }); }\n    });\n  }\n}\n\nexport interface SharedAuthentication {\n  cached?: { token: string; expiresAt: number } | undefined;\n  inFlight?: Promise<string> | undefined;\n}\nconst identities = new WeakMap<object, number>();\nlet nextIdentity = 1;\nexport function identity(value: object): number {\n  const prior = identities.get(value);\n  if (prior !== undefined) return prior;\n  const id = nextIdentity++; identities.set(value, id); return id;\n}\nconst authentication = new Map<string, SharedAuthentication>();\n/** Credentials are hashed for cache identity and never exposed in keys or diagnostics. */\nexport async function sharedAuthentication(scope: string, auth: ClientOptions[\"auth\"]): Promise<SharedAuthentication> {\n  const descriptor = auth.kind === \"credentials\" ? [scope, auth.kind, auth.username, auth.password] : auth.kind === \"provider\" ? [scope, auth.kind, identity(auth.getToken)] : [scope, auth.kind];\n  const digest = await crypto.subtle.digest(\"SHA-256\", new TextEncoder().encode(JSON.stringify(descriptor)));\n  const key = Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, \"0\")).join(\"\");\n  const prior = authentication.get(key);\n  if (prior) return prior;\n  const state: SharedAuthentication = {};\n  authentication.set(key, state);\n  return state;\n}\nexport const tokenMintQueue = new Semaphore(1);\n\nexport class RequestControl {\n  readonly semaphore: Semaphore;\n  readonly #settings: { threshold: number; windowMs: number; durationMs: number };\n  #failures: number[] = [];\n  #until = 0;\n  tokenMintCount = 0;\n  constructor(concurrency: number, settings: { threshold: number; windowMs: number; durationMs: number }) {\n    for (const value of [concurrency, settings.threshold, settings.windowMs, settings.durationMs]) if (!Number.isSafeInteger(value) || value < 1) throw new TypeError(\"Concurrency and cooldown settings must be positive integers\");\n    this.semaphore = new Semaphore(concurrency); this.#settings = { ...settings };\n  }\n  check(operation: string): void {\n    if (this.#until > Date.now()) throw new CooldownError(operation, this.#until);\n    if (this.#until !== 0) { this.#until = 0; this.#failures = []; }\n  }\n  failed(status: number): number | undefined {\n    if (status !== 401 && status !== 403 && status !== 429 && status < 500) return undefined;\n    const now = Date.now();\n    this.#failures = this.#failures.filter(time => time > now - this.#settings.windowMs);\n    this.#failures.push(now);\n    if (this.#failures.length >= this.#settings.threshold && this.#until <= now) { this.#until = now + this.#settings.durationMs; return this.#until; }\n    return undefined;\n  }\n  health(): ClientHealth {\n    return { state: this.#until > Date.now() ? \"open\" : \"closed\", until: this.#until > Date.now() ? new Date(this.#until).toISOString() : null, activeRequests: this.semaphore.active, queuedRequests: this.semaphore.queued, tokenMintCount: this.tokenMintCount };\n  }\n}\nconst controls = new Map<string, { signature: string; value: RequestControl }>();\nexport function requestControl(scope: string, options: ClientOptions): RequestControl {\n  const concurrency = options.maxConcurrency ?? 8;\n  const cooldown = options.cooldown ?? { threshold: 5, windowMs: 10_000, durationMs: 30_000 };\n  const signature = JSON.stringify([concurrency, cooldown.threshold, cooldown.windowMs, cooldown.durationMs]);\n  const existing = controls.get(scope);\n  if (existing && existing.signature !== signature) throw new TypeError(\"Clients sharing a tenant and transport must use the same concurrency/cooldown settings\");\n  if (existing) return existing.value;\n  const value = new RequestControl(concurrency, cooldown);\n  controls.set(scope, { signature, value }); return value;\n}\n\nexport function emit(options: Pick<ClientOptions, \"hooks\" | \"logger\">, event: ClientEvent): void {\n  const hooks = options.hooks;\n  const handler = event.type === \"request\" ? hooks?.onRequest : event.type === \"response\" ? hooks?.onResponse : event.type === \"tokenMint\" ? hooks?.onTokenMint : event.type === \"throttle\" ? hooks?.onThrottle : hooks?.onCooldown;\n  const safe = Object.freeze({ ...event });\n  // Observers must not turn a completed write into a thrown error or a replay.\n  try { void Promise.resolve(handler?.(safe)).catch(() => {}); } catch { /* Observer failures cannot change request outcomes. */ }\n  try { void Promise.resolve(options.logger?.(safe)).catch(() => {}); } catch { /* Same boundary for user-supplied loggers. */ }\n}\n"]}

package/dist/cjs/effective-date.d.ts

@@ -0,0 +1,3 @@
+/** Explicit deployment correction for an observed upstream mobile-write date shift. */
+export declare function correctMobileEffectiveDate(value: unknown, minutes: number, operation: string): string;
+//# sourceMappingURL=effective-date.d.ts.map

package/dist/cjs/effective-date.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effective-date.d.ts","sourceRoot":"","sources":["../../src/effective-date.ts"],"names":[],"mappings":"AAEA,uFAAuF;AACvF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAcrG"}

package/dist/cjs/effective-date.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.correctMobileEffectiveDate = correctMobileEffectiveDate;
+const errors_js_1 = require("./errors.js");
+/** Explicit deployment correction for an observed upstream mobile-write date shift. */
+function correctMobileEffectiveDate(value, minutes, operation) {
+    const invalid = () => new errors_js_1.ValidationError(operation, ["dateEffective"]);
+    if (typeof value !== "string")
+        throw invalid();
+    const parts = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?(Z|[+-]\d{2}:\d{2})$/.exec(value);
+    if (!parts)
+        throw invalid();
+    const [, year, month, day, hour, minute, second, , zone] = parts;
+    const date = new Date(`${year}-${month}-${day}T00:00:00.000Z`);
+    if (!Number.isFinite(date.getTime()) || date.toISOString().slice(0, 10) !== `${year}-${month}-${day}` || Number(hour) > 23 || Number(minute) > 59 || Number(second) > 59)
+        throw invalid();
+    if (zone !== "Z" && (!zone || Number(zone.slice(1, 3)) > 14 || Number(zone.slice(4)) > 59 || (Number(zone.slice(1, 3)) === 14 && Number(zone.slice(4)) !== 0)))
+        throw invalid();
+    const corrected = Date.parse(value) + minutes * 60_000;
+    if (!Number.isFinite(corrected))
+        throw invalid();
+    const encoded = new Date(corrected).toISOString();
+    if (!/^\d{4}-/.test(encoded))
+        throw invalid();
+    return encoded;
+}
+//# sourceMappingURL=effective-date.js.map

package/dist/cjs/effective-date.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effective-date.js","sourceRoot":"","sources":["../../src/effective-date.ts"],"names":[],"mappings":";;AAGA,gEAcC;AAjBD,2CAA8C;AAE9C,uFAAuF;AACvF,SAAgB,0BAA0B,CAAC,KAAc,EAAE,OAAe,EAAE,SAAiB;IAC3F,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,IAAI,2BAAe,CAAC,SAAS,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC;IACxE,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,MAAM,OAAO,EAAE,CAAC;IAC/C,MAAM,KAAK,GAAG,sFAAsF,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACjH,IAAI,CAAC,KAAK;QAAE,MAAM,OAAO,EAAE,CAAC;IAC5B,MAAM,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,AAAD,EAAG,IAAI,CAAC,GAAG,KAAK,CAAC;IACjE,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,GAAG,IAAI,IAAI,KAAK,IAAI,GAAG,gBAAgB,CAAC,CAAC;IAC/D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI,GAAG,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE;QAAE,MAAM,OAAO,EAAE,CAAC;IAC1L,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QAAE,MAAM,OAAO,EAAE,CAAC;IAChL,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,OAAO,GAAG,MAAM,CAAC;IACvD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,MAAM,OAAO,EAAE,CAAC;IACjD,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;IAClD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,MAAM,OAAO,EAAE,CAAC;IAC9C,OAAO,OAAO,CAAC;AACjB,CAAC","sourcesContent":["import { ValidationError } from \"./errors.js\";\n\n/** Explicit deployment correction for an observed upstream mobile-write date shift. */\nexport function correctMobileEffectiveDate(value: unknown, minutes: number, operation: string): string {\n  const invalid = () => new ValidationError(operation, [\"dateEffective\"]);\n  if (typeof value !== \"string\") throw invalid();\n  const parts = /^(\\d{4})-(\\d{2})-(\\d{2})T(\\d{2}):(\\d{2}):(\\d{2})(?:\\.(\\d{1,3}))?(Z|[+-]\\d{2}:\\d{2})$/.exec(value);\n  if (!parts) throw invalid();\n  const [, year, month, day, hour, minute, second, , zone] = parts;\n  const date = new Date(`${year}-${month}-${day}T00:00:00.000Z`);\n  if (!Number.isFinite(date.getTime()) || date.toISOString().slice(0, 10) !== `${year}-${month}-${day}` || Number(hour) > 23 || Number(minute) > 59 || Number(second) > 59) throw invalid();\n  if (zone !== \"Z\" && (!zone || Number(zone.slice(1, 3)) > 14 || Number(zone.slice(4)) > 59 || (Number(zone.slice(1, 3)) === 14 && Number(zone.slice(4)) !== 0))) throw invalid();\n  const corrected = Date.parse(value) + minutes * 60_000;\n  if (!Number.isFinite(corrected)) throw invalid();\n  const encoded = new Date(corrected).toISOString();\n  if (!/^\\d{4}-/.test(encoded)) throw invalid();\n  return encoded;\n}\n"]}

package/dist/cjs/encoding.d.ts

@@ -0,0 +1,32 @@
+import type { PicklistOption, PicklistSelector, QuestionDefinition } from "./metadata.js";
+export type AnswerState = "client_doesnt_know" | "client_refused" | "data_not_collected";
+export type AnswerValue = {
+    value: string | number | boolean | string[];
+} | {
+    state: AnswerState;
+} | {
+    option: PicklistSelector;
+} | {
+    options: readonly PicklistSelector[];
+};
+export type Answers = Record<string, AnswerValue>;
+export interface EncodingOptions {
+    endpoint: "standalone" | "enrollment" | "mobile";
+    /** Tenant-verified display labels, including exact whitespace/HUD suffixes, for label-based endpoints. */
+    writeLabel?: (question: QuestionDefinition, option: PicklistOption) => string | undefined;
+    /** Application configuration supplies the relevant option codes. No answer-state labels are guessed. */
+    stateCodes?: Partial<Record<AnswerState, readonly string[]>>;
+    multiValue?: (question: QuestionDefinition, values: readonly string[]) => string;
+}
+export interface EncodedQuestion {
+    question_id: number;
+    question_type: string;
+    virt_field_name: string;
+    answer_value: string;
+}
+export declare function encodeAnswers(questions: readonly QuestionDefinition[], answers: Answers, options: EncodingOptions): EncodedQuestion[];
+/** Builds one new row only. Never accepts or echoes an existing recordset ID. */
+export declare function encodeNewSubassessmentRow(parent: QuestionDefinition, answers: Answers, options: EncodingOptions): {
+    subAssessments: EncodedQuestion[];
+};
+//# sourceMappingURL=encoding.d.ts.map

package/dist/cjs/encoding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/encoding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAK1F,MAAM,MAAM,WAAW,GAAG,oBAAoB,GAAG,gBAAgB,GAAG,oBAAoB,CAAC;AACzF,MAAM,MAAM,WAAW,GAAG;IAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,WAAW,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,gBAAgB,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAA;CAAE,CAAC;AAC7K,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAClD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,YAAY,GAAG,YAAY,GAAG,QAAQ,CAAC;IACjD,0GAA0G;IAC1G,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,kBAAkB,EAAE,MAAM,EAAE,cAAc,KAAK,MAAM,GAAG,SAAS,CAAC;IAC1F,wGAAwG;IACxG,UAAU,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IAC7D,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,kBAAkB,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC;CAClF;AACD,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;CACtB;AA2DD,wBAAgB,aAAa,CAAC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,GAAG,eAAe,EAAE,CAgBrI;AAED,iFAAiF;AACjF,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,kBAAkB,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,GAAG;IAAE,cAAc,EAAE,eAAe,EAAE,CAAA;CAAE,CAUvJ"}