@whatsapi.sh/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 whatsapi.sh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# @whatsapi.sh/sdk
+
+The official TypeScript client for [whatsapi.sh](https://whatsapi.sh) — send WhatsApp
+messages, media and one-time codes through numbers you pair yourself, and receive
+signed events back.
+
+Every method, type and doc comment in this package is generated from the API's own
+operation definitions, so what TypeScript tells you here is what the server actually
+does.
+
+```bash
+npm install @whatsapi.sh/sdk
+```
+
+## Send a message
+
+```ts
+import { Whatsapi } from "@whatsapi.sh/sdk";
+
+const wa = new Whatsapi({ apiKey: process.env.WHATSAPI_KEY! });
+
+const message = await wa.sendMessage({
+  to: "+5511988887777",
+  text: "Your table is ready.",
+});
+
+console.log(message.id, message.quotaRemaining);
+```
+
+The key comes from [the dashboard](https://app.whatsapi.sh/keys). With a single
+connected number you never name a sender; with several, pass `from`.
+
+## Pair a number
+
+A number is a slot on your account plus a real WhatsApp session linked to it. Create
+the slot, then pair it by QR (scan from **WhatsApp → Linked devices**) or by an
+8-character code typed into the phone:
+
+```ts
+const number = await wa.createNumber({ name: "Support" });
+
+const pairing = await wa.pairNumber({ numberId: number.id, mode: "qr" });
+if (pairing.qrCode) showToUser(pairing.qrCode); // base64 PNG, good for ~90s
+```
+
+`pairNumber` is also the poll: call it again while `state` is `"pairing"` and no code
+has been minted yet. A fresh QR can only be generated every few minutes, so reuse the
+one you have (`isCached`, `generatedAt`, `remainingCooldown` all say where you stand).
+
+## One-time codes
+
+`sendOtp` generates the code, sends it, and hands it back — verify it yourself, or let
+us do it and keep nothing:
+
+```ts
+const otp = await wa.sendOtp({ to: "+5511988887777" });
+// …later, with what the user typed:
+await wa.checkOtp({ to: "+5511988887777", code: "123456" });
+```
+
+A wrong or expired code throws `OTP_INVALID` rather than answering "not verified" — a
+check you forget to read can never look like a pass.
+
+## Receive events
+
+One endpoint per account receives all five events, signed. Verify before you trust:
+
+```ts
+import { verifyWebhook, WebhookSignatureError } from "@whatsapi.sh/sdk";
+
+app.post("/webhooks/whatsapp", express.raw({ type: "application/json" }), async (req, res) => {
+  try {
+    const event = await verifyWebhook({
+      payload: req.body,                            // the RAW body, not the parsed one
+      signature: req.header("x-whatsapi-signature"),
+      secret: process.env.WHATSAPI_WEBHOOK_SECRET!,
+    });
+
+    if (event.type === "message.created") {
+      await reply(event.data.number.id, event.data.message.text ?? "");
+    }
+    res.sendStatus(200);
+  } catch (error) {
+    res.sendStatus(error instanceof WebhookSignatureError ? 400 : 500);
+  }
+});
+```
+
+`event.type` narrows `event.data`, so the compiler knows a `message.status` event has
+`messageIds` and a `number.logged_out` event does not. Deliveries retry, so the same
+`event.id` can arrive twice — record it and drop repeats.
+
+## Errors
+
+Every failure is a `WhatsapiError` carrying the API's own `code`, plus `status`,
+`retryAfter` and the `requestId` to quote at support.
+
+```ts
+import { WhatsapiError } from "@whatsapi.sh/sdk";
+
+try {
+  await wa.sendMessage({ to, text });
+} catch (error) {
+  if (!(error instanceof WhatsapiError)) throw error;
+
+  if (error.code === "PAYMENT_REQUIRED") return askThemToUpgrade();
+  if (error.code === "NUMBER_NOT_CONNECTED") return askThemToPairAgain();
+  if (error.code === "GATEWAY_TIMEOUT") return watchFor(error.messageId); // see below
+  throw error;
+}
+```
+
+Two rules worth knowing before you write a retry loop of your own:
+
+- **`GATEWAY_TIMEOUT` is not a failure.** WhatsApp did not confirm in time, but the
+  send was accepted and most likely delivered. Sending again sends twice. Watch for
+  `error.messageId` on the `message.status` webhook instead.
+- **`PAYMENT_REQUIRED` never clears by waiting**, unlike `RATE_LIMIT_EXCEEDED` and
+  `QUOTA_EXCEEDED`, which carry a `retryAfter`.
+
+This client retries **reads** (a failed `GET`, twice by default, honoring
+`Retry-After`) and never retries a write. There is no idempotency key on the API yet,
+so an automatic retry of a send would be a second real message to a real person — that
+call is yours to make, deliberately.
+
+## Agents
+
+If you are wiring up an LLM rather than an app, you probably want the MCP server
+instead of this package: the same operations, as tools, at
+`https://api.whatsapi.sh/mcp` with the same `wa_` key. See
+[the MCP reference](https://docs.whatsapi.sh/mcp).
+
+## Before you ship
+
+whatsapi.sh runs on the **unofficial** WhatsApp protocol — the same one WhatsApp Web
+uses. It is not the WhatsApp Business API, there is no Meta approval, and WhatsApp can
+restrict or ban a number that behaves like a broadcaster. Cold outreach, identical
+messages at speed and large recipient lists are what gets numbers banned. Pace your
+sends, message people who expect you, and do not put a number you cannot afford to
+lose on it. We tell you this before you pair, not after.
+
+## Requirements
+
+Node 20+, or any runtime with `fetch` and Web Crypto (Bun, Deno, Cloudflare Workers,
+the browser — though a `wa_` key does not belong in a browser). ESM only; on Node
+22.12+ `require("@whatsapi.sh/sdk")` works too.
+
+- Docs: [docs.whatsapi.sh](https://docs.whatsapi.sh)
+- REST reference: [docs.whatsapi.sh/reference](https://docs.whatsapi.sh/reference)

package/dist/client.d.ts

@@ -0,0 +1,35 @@
+import { GeneratedOperations } from "./generated/operations.ts";
+export interface WhatsapiOptions {
+    /** A `wa_` key from the dashboard. */
+    apiKey: string;
+    /** Defaults to the hosted API; point it at a self-hosted deployment if you run one. */
+    baseUrl?: string;
+    /** Per-attempt timeout in ms. Default 30000. */
+    timeout?: number;
+    /** Extra attempts for READ calls only. Default 2, 0 disables. */
+    maxRetries?: number;
+    /** Swap the fetch implementation (tests, proxies, a custom agent). */
+    fetch?: typeof globalThis.fetch;
+}
+/** What a generated method hands the transport. */
+export interface RequestSpec {
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    /** Template with `:name` placeholders naming the params that fill them. */
+    path: string;
+    pathParams?: readonly string[];
+    /** Values the ROUTE fixes rather than the caller. */
+    fixed?: Readonly<Record<string, unknown>>;
+}
+export declare class Whatsapi extends GeneratedOperations {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    constructor(options: WhatsapiOptions | string);
+    protected request<T>(spec: RequestSpec, params?: object): Promise<T>;
+    /** How long to wait before repeating a read, or undefined to give up now. */
+    private retryDelay;
+    private attempt;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAUA,OAAO,EAAoB,mBAAmB,EAAe,MAAM,2BAA2B,CAAC;AAE/F,MAAM,WAAW,eAAe;IAC5B,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACnC;AAED,mDAAmD;AACnD,MAAM,WAAW,WAAW;IACxB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC1C,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,qDAAqD;IACrD,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC7C;AA6BD,qBAAa,QAAS,SAAQ,mBAAmB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;gBAExC,OAAO,EAAE,eAAe,GAAG,MAAM;cAqB7B,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,GAAE,MAAW,GAAG,OAAO,CAAC,CAAC,CAAC;IAgB9E,6EAA6E;IAC7E,OAAO,CAAC,UAAU;YAkBJ,OAAO;CA8ExB"}

package/dist/client.js

@@ -0,0 +1,169 @@
+// The transport under every generated method: one request, one `{ data }`
+// unwrap, one error taxonomy.
+//
+// The retry policy is the opinionated part, and it is deliberately narrow:
+// READS retry, WRITES never do. There is no idempotency key on /v1, so a
+// retried send is a second WhatsApp message to a real person and a second unit
+// off the quota — worse than the failure it was papering over. Writes come back
+// as a WhatsapiError carrying `code` and `retryAfter`, and the caller decides.
+import { WhatsapiError } from "./errors.js";
+import { DEFAULT_BASE_URL, GeneratedOperations, SDK_VERSION } from "./generated/operations.js";
+/** A Retry-After we would honor beyond this is not a retry, it is a hang — the
+ *  caller gets the error (with `retryAfter` on it) and schedules it themselves. */
+const MAX_RETRY_DELAY_MS = 10_000;
+/** How the API answers when it never got to answer at all. */
+function statusCode(status) {
+    if (status === 503)
+        return "SERVICE_UNAVAILABLE";
+    if (status === 404)
+        return "NOT_FOUND";
+    if (status === 401)
+        return "UNAUTHORIZED";
+    return "INTERNAL_ERROR";
+}
+/** Seconds from `Retry-After` (delta form) or the error's own details. */
+function retryAfterOf(header, details) {
+    const fromDetails = typeof details === "object" && details !== null
+        ? details.retryAfterSecs
+        : undefined;
+    if (typeof fromDetails === "number" && Number.isFinite(fromDetails))
+        return fromDetails;
+    const seconds = header === null ? NaN : Number(header);
+    return Number.isFinite(seconds) ? seconds : undefined;
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class Whatsapi extends GeneratedOperations {
+    apiKey;
+    baseUrl;
+    timeout;
+    maxRetries;
+    fetchImpl;
+    constructor(options) {
+        super();
+        const opts = typeof options === "string" ? { apiKey: options } : options;
+        if (!opts.apiKey)
+            throw new TypeError("whatsapi: an API key is required — create one at https://app.whatsapi.sh/keys");
+        this.apiKey = opts.apiKey;
+        // Trailing slashes would double up against the leading slash of a path.
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.timeout = opts.timeout ?? 30_000;
+        this.maxRetries = opts.maxRetries ?? 2;
+        const impl = opts.fetch ?? globalThis.fetch;
+        if (typeof impl !== "function")
+            throw new TypeError("whatsapi: no global fetch — use Node 20+, or pass `fetch` in the options.");
+        // Bound: an unbound global fetch throws "Illegal invocation" in browsers.
+        this.fetchImpl = opts.fetch ?? impl.bind(globalThis);
+    }
+    async request(spec, params = {}) {
+        // Reads are the only calls we may repeat: a re-sent message is a second
+        // message to a real person, and no header on /v1 makes it idempotent.
+        const retries = spec.method === "GET" ? this.maxRetries : 0;
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await this.attempt(spec, params);
+            }
+            catch (error) {
+                if (!(error instanceof WhatsapiError) || attempt >= retries)
+                    throw error;
+                const delay = this.retryDelay(error, attempt);
+                if (delay === undefined)
+                    throw error;
+                await sleep(delay);
+            }
+        }
+    }
+    /** How long to wait before repeating a read, or undefined to give up now. */
+    retryDelay(error, attempt) {
+        const worthRepeating = error.code === "NETWORK_ERROR" ||
+            error.code === "TIMEOUT" ||
+            error.code === "RATE_LIMIT_EXCEEDED" ||
+            // A quota clears when the month rolls over and a pairing cooldown
+            // runs for minutes: both are answers, not hiccups.
+            (error.status >= 500 && error.code !== "GATEWAY_TIMEOUT");
+        if (!worthRepeating)
+            return undefined;
+        if (error.retryAfter !== undefined) {
+            const ms = error.retryAfter * 1000;
+            return ms > MAX_RETRY_DELAY_MS ? undefined : ms;
+        }
+        // Exponential with jitter, so a fleet of clients does not resynchronize
+        // onto the same second after an outage.
+        return Math.min(250 * 2 ** attempt, 4_000) * (0.5 + Math.random());
+    }
+    async attempt(spec, params) {
+        const rest = { ...params };
+        let path = spec.path;
+        for (const name of spec.pathParams ?? []) {
+            const value = rest[name];
+            if (value === undefined || value === null || value === "")
+                throw new TypeError(`whatsapi: \`${name}\` is required`);
+            delete rest[name];
+            path = path.replace(`:${name}`, encodeURIComponent(String(value)));
+        }
+        const url = new URL(this.baseUrl + path);
+        const hasBody = spec.method === "POST" || spec.method === "PUT";
+        if (!hasBody)
+            for (const [key, value] of Object.entries(rest))
+                if (value !== undefined && value !== null)
+                    url.searchParams.set(key, String(value));
+        const headers = {
+            authorization: `Bearer ${this.apiKey}`,
+            accept: "application/json",
+            "x-whatsapi-client": `whatsapi-js/${SDK_VERSION}`,
+        };
+        if (hasBody)
+            headers["content-type"] = "application/json";
+        let response;
+        try {
+            response = await this.fetchImpl(url.toString(), {
+                method: spec.method,
+                headers,
+                ...(hasBody
+                    ? { body: JSON.stringify({ ...rest, ...(spec.fixed ?? {}) }) }
+                    : undefined),
+                signal: AbortSignal.timeout(this.timeout),
+            });
+        }
+        catch (cause) {
+            const timedOut = cause instanceof Error && cause.name === "TimeoutError";
+            throw new WhatsapiError({
+                code: (timedOut ? "TIMEOUT" : "NETWORK_ERROR"),
+                status: 0,
+                message: timedOut
+                    ? `whatsapi: no answer within ${this.timeout}ms — the call may still have gone through.`
+                    : `whatsapi: could not reach ${url.host}.`,
+                cause,
+            });
+        }
+        const requestId = response.headers.get("x-request-id") ?? undefined;
+        const text = await response.text();
+        let payload;
+        try {
+            payload = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            payload = undefined;
+        }
+        if (response.ok)
+            return payload.data;
+        const envelope = typeof payload === "object" && payload !== null
+            ? payload.error
+            : undefined;
+        const details = envelope?.details;
+        throw new WhatsapiError({
+            code: envelope?.code ?? statusCode(response.status),
+            status: response.status,
+            // A proxy or a cold start can answer HTML; say what actually came back
+            // rather than pretending the body was ours.
+            message: typeof envelope?.message === "string"
+                ? envelope.message
+                : `whatsapi: ${spec.method} ${path} failed with ${response.status}.`,
+            messageKey: typeof envelope?.messageKey === "string" ? envelope.messageKey : undefined,
+            params: envelope?.params,
+            details: envelope ? details : text.slice(0, 500) || undefined,
+            retryAfter: retryAfterOf(response.headers.get("retry-after"), details),
+            requestId,
+        });
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,40 @@
+import type { ErrorCode } from "./generated/contract.ts";
+/** Failures that never reached the API, so they carry no server code. */
+export type ClientErrorCode = "NETWORK_ERROR" | "TIMEOUT";
+export interface WhatsapiErrorInit {
+    code: ErrorCode | ClientErrorCode;
+    message: string;
+    /** HTTP status, or 0 when no answer arrived. */
+    status: number;
+    messageKey?: string;
+    params?: Record<string, string | number>;
+    details?: unknown;
+    /** Seconds until the call is worth making again, when the API said. */
+    retryAfter?: number;
+    /** `X-Request-ID` — quote it in a support request and we can find the call. */
+    requestId?: string;
+    cause?: unknown;
+}
+export declare class WhatsapiError extends Error {
+    readonly code: ErrorCode | ClientErrorCode;
+    readonly status: number;
+    readonly messageKey?: string;
+    readonly params?: Record<string, string | number>;
+    readonly details?: unknown;
+    readonly retryAfter?: number;
+    readonly requestId?: string;
+    constructor(init: WhatsapiErrorInit);
+    /** The id a timed-out send went out with.
+     *
+     *  `GATEWAY_TIMEOUT` means WhatsApp did not confirm in time — NOT that the
+     *  message failed. It was accepted upstream and most likely delivered, so
+     *  sending it again sends it twice. Watch for this id on the
+     *  `message.status` webhook instead. */
+    get messageId(): string | undefined;
+}
+/** A delivery whose signature did not check out — treat the body as hostile and
+ *  answer 400. Never a WhatsapiError: nothing here came from a call we made. */
+export declare class WebhookSignatureError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,yEAAyE;AACzE,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG,SAAS,CAAC;AAE1D,MAAM,WAAW,iBAAiB;IAC9B,IAAI,EAAE,SAAS,GAAG,eAAe,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IACzC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,aAAc,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,eAAe,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;gBAEhB,IAAI,EAAE,iBAAiB;IAYnC;;;;;4CAKwC;IACxC,IAAI,SAAS,IAAI,MAAM,GAAG,SAAS,CAMlC;CACJ;AAED;gFACgF;AAChF,qBAAa,qBAAsB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI9B"}

package/dist/errors.js

@@ -0,0 +1,42 @@
+export class WhatsapiError extends Error {
+    code;
+    status;
+    messageKey;
+    params;
+    details;
+    retryAfter;
+    requestId;
+    constructor(init) {
+        super(init.message, init.cause !== undefined ? { cause: init.cause } : undefined);
+        this.name = "WhatsapiError";
+        this.code = init.code;
+        this.status = init.status;
+        this.messageKey = init.messageKey;
+        this.params = init.params;
+        this.details = init.details;
+        this.retryAfter = init.retryAfter;
+        this.requestId = init.requestId;
+    }
+    /** The id a timed-out send went out with.
+     *
+     *  `GATEWAY_TIMEOUT` means WhatsApp did not confirm in time — NOT that the
+     *  message failed. It was accepted upstream and most likely delivered, so
+     *  sending it again sends it twice. Watch for this id on the
+     *  `message.status` webhook instead. */
+    get messageId() {
+        const details = this.details;
+        if (this.code !== "GATEWAY_TIMEOUT" || typeof details !== "object" || details === null)
+            return undefined;
+        const id = details.messageId;
+        return typeof id === "string" ? id : undefined;
+    }
+}
+/** A delivery whose signature did not check out — treat the body as hostile and
+ *  answer 400. Never a WhatsapiError: nothing here came from a call we made. */
+export class WebhookSignatureError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WebhookSignatureError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AA2BA,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC3B,IAAI,CAA8B;IAClC,MAAM,CAAS;IACf,UAAU,CAAU;IACpB,MAAM,CAAmC;IACzC,OAAO,CAAW;IAClB,UAAU,CAAU;IACpB,SAAS,CAAU;IAE5B,YAAY,IAAuB;QAC/B,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAClF,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAClC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAClC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IACpC,CAAC;IAED;;;;;4CAKwC;IACxC,IAAI,SAAS;QACT,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC7B,IAAI,IAAI,CAAC,IAAI,KAAK,iBAAiB,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;YAClF,OAAO,SAAS,CAAC;QACrB,MAAM,EAAE,GAAI,OAAmC,CAAC,SAAS,CAAC;QAC1D,OAAO,OAAO,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACnD,CAAC;CACJ;AAED;gFACgF;AAChF,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC5C,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACxC,CAAC;CACJ"}