@xmodeai/sdk 0.1.0

package/dist/types-BLVayOx3.d.ts

@@ -0,0 +1,286 @@
+//#region src/types.d.ts
+/**
+ * Public wire types for the xMode API.
+ *
+ * These are hand-written and deliberately decoupled from the server's internal
+ * schemas so that:
+ *   - the published package carries ZERO runtime dependencies (no zod), and
+ *   - new server capabilities never break older SDK versions (forward-compat).
+ *
+ * Forward-compat rules applied below:
+ *   - "enum-ish" fields the caller SENDS (model, size) are widened with
+ *     `| (string & {})` so any future alias compiles while keeping autocomplete.
+ *   - response unions keep literal `status` branches so `switch (record.status)`
+ *     narrows cleanly; unknown statuses are handled by BEHAVIOR (polling treats
+ *     anything outside the terminal set as "in progress"), never by throwing.
+ *
+ * The `src/__contract__/shared-contract.ts` file statically checks these types
+ * against the server's zod schemas, so drift is caught at type-check time.
+ */
+type KnownImageModel = 'xSD4.5';
+type KnownVideoModel = 'xW2.7S';
+/** Image model alias. Known values autocomplete; any future alias also compiles. */
+type ImageModel = KnownImageModel | (string & {});
+/** Video model alias. Known values autocomplete; any future alias also compiles. */
+type VideoModel = KnownVideoModel | (string & {});
+type SizePreset = '2K' | '4K';
+/** Either a preset (`2K`, `4K`) or explicit `WxH` pixels (e.g. `2048x2048`). */
+type ImageSize = SizePreset | (string & {});
+type AspectRatio = 'auto' | 'square' | 'landscape' | 'portrait';
+type ResponseFormat = 'url' | 'b64_json';
+type VideoResolution = '720p' | '1080p';
+type KnownStatus = 'queued' | 'processing' | 'succeeded' | 'failed' | 'expired';
+/** Widened status for filters and forward-compat reads. */
+type Status = KnownStatus | (string & {});
+interface CreateGenerationInput {
+  /** Email of YOUR end-user who triggered this generation. Stored lowercase server-side. */
+  endUserEmail: string;
+  /** English text prompt. 1–8000 chars. */
+  prompt: string;
+  /** Public model alias, e.g. `'xSD4.5'`. */
+  model: ImageModel;
+  /** Reference image(s): a single HTTPS URL or an array of 1–10 URLs. */
+  references?: string | string[];
+  /** Output dimensions: preset (`2K`/`4K`) or explicit `WxH`. Defaults to `2K`. */
+  size?: ImageSize;
+  /** Aspect-ratio shortcut. Combined with a preset `size`, resolves to explicit pixels. */
+  aspectRatio?: AspectRatio;
+  /** How many images to generate, 1–15. Each is billed separately. */
+  n?: number;
+  /** Determinism seed. Omit for a random seed (returned in the record). */
+  seed?: number;
+  /** Add a small watermark. Defaults to false. */
+  watermark?: boolean;
+  /** Prompt-adherence strength, 1–20 (typical 5–10). */
+  guidanceScale?: number;
+  /** `'url'` (signed CDN URLs, default) or `'b64_json'` (inline base64). */
+  responseFormat?: ResponseFormat;
+  /** `'auto'` to produce a connected series (requires `sequentialOptions.maxImages`). */
+  sequential?: 'auto' | 'disabled';
+  /** Series length when `sequential: 'auto'`. */
+  sequentialOptions?: {
+    maxImages: number;
+  };
+  /** HTTPS URL we POST to once this generation reaches a terminal status. */
+  webhookUrl?: string;
+}
+interface ImageRecord {
+  /** Stable image id. */
+  id: string;
+  /** Signed URL, valid ~23h. Absent when `error` is set. */
+  url?: string;
+  /** Present only when the image is unavailable. Mutually exclusive with `url`. */
+  error?: {
+    code: 'storage_failed' | (string & {});
+  };
+  /** Actual dimensions returned by the model. */
+  size?: string;
+  /** When the signed URL stops working (ISO 8601). */
+  expiresAt: string;
+}
+interface GenerationCost {
+  xTokens: number;
+}
+interface GenerationError {
+  /** Stable error code, e.g. `content_policy`, `provider_error`. */
+  code: string;
+  /** Human-readable message, safe to surface to end-users. */
+  message: string;
+}
+interface GenerationRecordBase {
+  requestId: string;
+  model: string;
+  prompt: string;
+  referencesCount: number;
+  endUserEmail: string;
+  createdAt: string;
+}
+interface QueuedGenerationRecord extends GenerationRecordBase {
+  status: 'queued';
+  /** Path to GET to poll for status. */
+  pollUrl: string;
+}
+interface ProcessingGenerationRecord extends GenerationRecordBase {
+  status: 'processing';
+}
+interface SucceededGenerationRecord extends GenerationRecordBase {
+  status: 'succeeded';
+  images: ImageRecord[];
+  cost: GenerationCost;
+  finishedAt: string;
+}
+interface FailedGenerationRecord extends GenerationRecordBase {
+  status: 'failed';
+  error: GenerationError;
+  finishedAt: string;
+}
+interface ExpiredGenerationRecord extends GenerationRecordBase {
+  status: 'expired';
+  finishedAt: string;
+}
+/**
+ * Discriminated by `status`. Returned by `generations.get`, the items of
+ * `generations.list`, and the outbound webhook body. At runtime `status` may
+ * carry a value newer than this SDK version knows — handle the `default` branch.
+ */
+type GenerationRecord = QueuedGenerationRecord | ProcessingGenerationRecord | SucceededGenerationRecord | FailedGenerationRecord | ExpiredGenerationRecord;
+interface GenerationListParams {
+  page?: number;
+  pageSize?: number;
+  endUserEmail?: string;
+  status?: Status;
+  /** ISO 8601 — only generations created strictly after this instant. */
+  createdAfter?: string;
+}
+interface GenerationListResponse {
+  items: GenerationRecord[];
+  page: number;
+  pageSize: number;
+  hasMore: boolean;
+}
+/**
+ * Body for `POST /v1/videos` with `model: 'xW2.7S'`. Other video models, when
+ * added, may carry different params — send those via `client.request()` until
+ * a typed method ships.
+ */
+interface CreateVideoInput {
+  endUserEmail: string;
+  model: VideoModel;
+  prompt: string;
+  /** Input image to animate (HTTPS URL). */
+  image: string;
+  negative_prompt?: string;
+  /** Optional audio URL (HTTPS) to drive motion. */
+  audio_url?: string;
+  /** `'720p'` or `'1080p'`. Defaults to `'1080p'`. */
+  resolution?: VideoResolution;
+  /** Seconds, 2–15. Defaults to 5. Billed per second. */
+  duration?: number;
+  /** Auto-expand the prompt before generation. Defaults to true. */
+  prompt_extend?: boolean;
+  /** Determinism seed, 0–2147483647, or null for auto. */
+  seed?: number | null;
+  webhookUrl?: string;
+}
+interface VideoRecordItem {
+  id: string;
+  url?: string;
+  error?: {
+    code: 'storage_failed' | (string & {});
+  };
+  duration?: number;
+  resolution?: VideoResolution;
+  expiresAt: string;
+}
+interface VideoCost {
+  xTokens: number;
+}
+interface VideoError {
+  code: string;
+  message: string;
+}
+interface VideoRecordBase {
+  requestId: string;
+  model: string;
+  prompt: string;
+  endUserEmail: string;
+  createdAt: string;
+}
+interface QueuedVideoRecord extends VideoRecordBase {
+  status: 'queued';
+  pollUrl: string;
+}
+interface ProcessingVideoRecord extends VideoRecordBase {
+  status: 'processing';
+}
+interface SucceededVideoRecord extends VideoRecordBase {
+  status: 'succeeded';
+  videos: VideoRecordItem[];
+  cost: VideoCost;
+  finishedAt: string;
+}
+interface FailedVideoRecord extends VideoRecordBase {
+  status: 'failed';
+  error: VideoError;
+  finishedAt: string;
+}
+interface ExpiredVideoRecord extends VideoRecordBase {
+  status: 'expired';
+  finishedAt: string;
+}
+type VideoRecord = QueuedVideoRecord | ProcessingVideoRecord | SucceededVideoRecord | FailedVideoRecord | ExpiredVideoRecord;
+interface BalanceResponse {
+  xTokens: number;
+  updatedAt: string;
+}
+type BalanceLedgerType = 'debit' | 'credit';
+type BalanceLedgerReason = 'generation' | 'refund' | 'topup' | 'admin_adjustment';
+interface BalanceLedgerEntry {
+  id: string;
+  type: BalanceLedgerType;
+  amount: number;
+  reason: BalanceLedgerReason;
+  reference: string;
+  balanceAfter: number;
+  createdAt: string;
+}
+interface BalanceHistoryParams {
+  page?: number;
+  pageSize?: number;
+}
+interface BalanceHistoryResponse {
+  items: BalanceLedgerEntry[];
+  page: number;
+  pageSize: number;
+  hasMore: boolean;
+}
+interface EndUserRecord {
+  email: string;
+  createdAt: string;
+  lastActiveAt: string;
+  totalRequests: number;
+  totalXTokensSpent: number;
+  /** When the owner blocked this end-user (ISO 8601), or null when active. */
+  blockedAt: string | null;
+}
+interface EndUserListParams {
+  page?: number;
+  pageSize?: number;
+  /** Filter to only blocked (`true`) or only active (`false`) end-users. */
+  blocked?: boolean;
+  /** Case-insensitive substring match on email. */
+  email?: string;
+}
+interface EndUserListResponse {
+  items: EndUserRecord[];
+  page: number;
+  pageSize: number;
+  hasMore: boolean;
+}
+interface BlockEndUserResponse {
+  email: string;
+  blockedAt: string;
+}
+interface UnblockEndUserResponse {
+  email: string;
+  blockedAt: null;
+}
+interface DeleteEndUserResponse {
+  email: string;
+  deleted: true;
+  removedRequests: number;
+  removedObjects: number;
+}
+type KnownApiErrorCode = 'validation_error' | 'unauthorized' | 'forbidden' | 'not_found' | 'conflict' | 'rate_limited' | 'payment_required' | 'content_policy' | 'provider_timeout' | 'provider_error' | 'internal_error' | 'account_blocked';
+/** Widened so a server-added code never breaks error handling in older SDKs. */
+type ApiErrorCode = KnownApiErrorCode | (string & {});
+interface ApiErrorBody {
+  error: {
+    code: ApiErrorCode;
+    message: string;
+    fields?: Record<string, string>;
+  };
+}
+//#endregion
+export { KnownImageModel as A, SucceededGenerationRecord as B, GenerationListParams as C, ImageRecord as D, ImageModel as E, QueuedGenerationRecord as F, VideoModel as G, UnblockEndUserResponse as H, QueuedVideoRecord as I, VideoResolution as J, VideoRecord as K, ResponseFormat as L, KnownVideoModel as M, ProcessingGenerationRecord as N, ImageSize as O, ProcessingVideoRecord as P, SizePreset as R, GenerationError as S, GenerationRecord as T, VideoCost as U, SucceededVideoRecord as V, VideoError as W, ExpiredGenerationRecord as _, BalanceHistoryResponse as a, FailedVideoRecord as b, BalanceLedgerType as c, CreateGenerationInput as d, CreateVideoInput as f, EndUserRecord as g, EndUserListResponse as h, BalanceHistoryParams as i, KnownStatus as j, KnownApiErrorCode as k, BalanceResponse as l, EndUserListParams as m, ApiErrorCode as n, BalanceLedgerEntry as o, DeleteEndUserResponse as p, VideoRecordItem as q, AspectRatio as r, BalanceLedgerReason as s, ApiErrorBody as t, BlockEndUserResponse as u, ExpiredVideoRecord as v, GenerationListResponse as w, GenerationCost as x, FailedGenerationRecord as y, Status as z };
+//# sourceMappingURL=types-BLVayOx3.d.ts.map

package/dist/types-BLVayOx3.d.ts.map

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

package/dist/webhooks.cjs

@@ -0,0 +1,90 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/webhooks.ts
+var WebhookVerificationError = class extends Error {
+	reason;
+	constructor(message, reason) {
+		super(message);
+		this.name = "WebhookVerificationError";
+		this.reason = reason;
+	}
+};
+const encoder = new TextEncoder();
+const DEFAULT_TOLERANCE_SECONDS = 300;
+function getHeader(headers, name) {
+	if (typeof Headers !== "undefined" && headers instanceof Headers) return headers.get(name);
+	const target = name.toLowerCase();
+	for (const [key, value] of Object.entries(headers)) if (key.toLowerCase() === target) {
+		if (Array.isArray(value)) return value[0] ?? null;
+		return value ?? null;
+	}
+	return null;
+}
+function hexToBytes(hex) {
+	if (hex.length === 0 || hex.length % 2 !== 0 || /[^0-9a-fA-F]/.test(hex)) return null;
+	const bytes = new Uint8Array(hex.length / 2);
+	for (let i = 0; i < bytes.length; i++) bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+	return bytes;
+}
+/**
+* Verify a webhook delivery and parse its body. Resolves with the typed event,
+* or throws {@link WebhookVerificationError} (with a `reason`) on any failure.
+*
+* ```ts
+* import { verifyWebhook } from '@xmodeai/sdk/webhooks';
+* const { event } = await verifyWebhook({ payload: rawBody, headers: req.headers, secret });
+* ```
+*/
+async function verifyWebhook(options) {
+	const { payload, headers, secret } = options;
+	const tolerance = options.tolerance ?? DEFAULT_TOLERANCE_SECONDS;
+	const now = options.now ?? Date.now;
+	const signatureHeader = getHeader(headers, "x-xmode-signature");
+	const timestampHeader = getHeader(headers, "x-xmode-timestamp");
+	if (!signatureHeader || !timestampHeader) throw new WebhookVerificationError("Missing X-XMode-Signature or X-XMode-Timestamp header.", "missing_header");
+	const timestamp = Number(timestampHeader);
+	if (!Number.isFinite(timestamp)) throw new WebhookVerificationError("Malformed X-XMode-Timestamp header.", "malformed");
+	if (Math.abs(now() / 1e3 - timestamp) > tolerance) throw new WebhookVerificationError("Webhook timestamp is outside the allowed tolerance.", "timestamp_out_of_tolerance");
+	const candidates = signatureHeader.split(/[,\s]+/).filter((part) => part.startsWith("v1=")).map((part) => part.slice(3));
+	if (candidates.length === 0) throw new WebhookVerificationError("No v1 signature found in header.", "malformed");
+	const key = await crypto.subtle.importKey("raw", encoder.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["verify"]);
+	const message = encoder.encode(`${timestampHeader}.${payload}`);
+	let valid = false;
+	for (const hex of candidates) {
+		const signatureBytes = hexToBytes(hex);
+		if (!signatureBytes) continue;
+		if (await crypto.subtle.verify("HMAC", key, signatureBytes, message)) {
+			valid = true;
+			break;
+		}
+	}
+	if (!valid) throw new WebhookVerificationError("Webhook signature verification failed.", "invalid_signature");
+	let event;
+	try {
+		event = JSON.parse(payload);
+	} catch {
+		throw new WebhookVerificationError("Webhook payload is not valid JSON.", "malformed");
+	}
+	return {
+		event,
+		requestId: getHeader(headers, "x-xmode-request-id"),
+		timestamp
+	};
+}
+/** True when the event is a video record (image records carry `referencesCount`). */
+function isVideoEvent(event) {
+	return !("referencesCount" in event);
+}
+/** True when the event is an image generation record. */
+function isGenerationEvent(event) {
+	return "referencesCount" in event;
+}
+//#endregion
+exports.WebhookVerificationError = WebhookVerificationError;
+exports.isGenerationEvent = isGenerationEvent;
+exports.isVideoEvent = isVideoEvent;
+exports.verifyWebhook = verifyWebhook;
+
+//# sourceMappingURL=webhooks.cjs.map

package/dist/webhooks.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.cjs","names":[],"sources":["../src/webhooks.ts"],"sourcesContent":["/**\n * Webhook verification — published at the `@xmodeai/sdk/webhooks` subpath.\n *\n * Uses Web Crypto (`crypto.subtle`) only, so it runs unchanged on Node 18+,\n * Deno, Bun, Cloudflare Workers and other edge runtimes without `node:crypto`.\n *\n * Outbound signature contract (what xMode sends):\n *   X-XMode-Signature:  v1=<hex(HMAC_SHA256(secret, \"<timestamp>.<rawBody>\"))>\n *   X-XMode-Timestamp:  unix seconds when the payload was built\n *   X-XMode-Request-Id: requestId (handy for client-side dedup)\n */\nimport type { GenerationRecord, VideoRecord } from './types';\n\nexport type WebhookVerificationReason =\n  | 'missing_header'\n  | 'invalid_signature'\n  | 'timestamp_out_of_tolerance'\n  | 'malformed';\n\nexport class WebhookVerificationError extends Error {\n  readonly reason: WebhookVerificationReason;\n  constructor(message: string, reason: WebhookVerificationReason) {\n    super(message);\n    this.name = 'WebhookVerificationError';\n    this.reason = reason;\n  }\n}\n\n/** The webhook body is the same shape as `generations.get` / `videos.get`. */\nexport type XModeWebhookEvent = GenerationRecord | VideoRecord;\n\nexport type HeadersLike = Headers | Record<string, string | string[] | undefined>;\n\nexport interface VerifyWebhookOptions {\n  /** The RAW request body string. Must NOT be a re-serialized object. */\n  payload: string;\n  /** Request headers, as a `Headers` object or a plain record. */\n  headers: HeadersLike;\n  /** Your account webhook signing secret. */\n  secret: string;\n  /** Allowed clock skew in seconds. Defaults to 300 (5 minutes). */\n  tolerance?: number;\n  /** Clock injection for tests; returns ms since epoch. Defaults to `Date.now`. */\n  now?: () => number;\n}\n\nexport interface VerifiedWebhook {\n  event: XModeWebhookEvent;\n  requestId: string | null;\n  timestamp: number;\n}\n\nconst encoder = new TextEncoder();\nconst DEFAULT_TOLERANCE_SECONDS = 300;\n\nfunction getHeader(headers: HeadersLike, name: string): string | null {\n  if (typeof Headers !== 'undefined' && headers instanceof Headers) {\n    return headers.get(name);\n  }\n  const target = name.toLowerCase();\n  for (const [key, value] of Object.entries(headers)) {\n    if (key.toLowerCase() === target) {\n      if (Array.isArray(value)) return value[0] ?? null;\n      return value ?? null;\n    }\n  }\n  return null;\n}\n\nfunction hexToBytes(hex: string): Uint8Array | null {\n  if (hex.length === 0 || hex.length % 2 !== 0 || /[^0-9a-fA-F]/.test(hex)) return null;\n  const bytes = new Uint8Array(hex.length / 2);\n  for (let i = 0; i < bytes.length; i++) {\n    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);\n  }\n  return bytes;\n}\n\n/**\n * Verify a webhook delivery and parse its body. Resolves with the typed event,\n * or throws {@link WebhookVerificationError} (with a `reason`) on any failure.\n *\n * ```ts\n * import { verifyWebhook } from '@xmodeai/sdk/webhooks';\n * const { event } = await verifyWebhook({ payload: rawBody, headers: req.headers, secret });\n * ```\n */\nexport async function verifyWebhook(options: VerifyWebhookOptions): Promise<VerifiedWebhook> {\n  const { payload, headers, secret } = options;\n  const tolerance = options.tolerance ?? DEFAULT_TOLERANCE_SECONDS;\n  const now = options.now ?? Date.now;\n\n  const signatureHeader = getHeader(headers, 'x-xmode-signature');\n  const timestampHeader = getHeader(headers, 'x-xmode-timestamp');\n  if (!signatureHeader || !timestampHeader) {\n    throw new WebhookVerificationError(\n      'Missing X-XMode-Signature or X-XMode-Timestamp header.',\n      'missing_header',\n    );\n  }\n\n  const timestamp = Number(timestampHeader);\n  if (!Number.isFinite(timestamp)) {\n    throw new WebhookVerificationError('Malformed X-XMode-Timestamp header.', 'malformed');\n  }\n  if (Math.abs(now() / 1000 - timestamp) > tolerance) {\n    throw new WebhookVerificationError(\n      'Webhook timestamp is outside the allowed tolerance.',\n      'timestamp_out_of_tolerance',\n    );\n  }\n\n  // Header is `v1=<hex>`; tolerate several space/comma-separated entries (rotation).\n  const candidates = signatureHeader\n    .split(/[,\\s]+/)\n    .filter((part) => part.startsWith('v1='))\n    .map((part) => part.slice(3));\n  if (candidates.length === 0) {\n    throw new WebhookVerificationError('No v1 signature found in header.', 'malformed');\n  }\n\n  const key = await crypto.subtle.importKey(\n    'raw',\n    encoder.encode(secret) as BufferSource,\n    { name: 'HMAC', hash: 'SHA-256' },\n    false,\n    ['verify'],\n  );\n  // Sign over the RAW timestamp header, not the parsed number, so verification\n  // never depends on the server using a canonical integer representation.\n  const message = encoder.encode(`${timestampHeader}.${payload}`) as BufferSource;\n\n  let valid = false;\n  for (const hex of candidates) {\n    const signatureBytes = hexToBytes(hex);\n    if (!signatureBytes) continue;\n    // crypto.subtle.verify is constant-time internally.\n    if (await crypto.subtle.verify('HMAC', key, signatureBytes as BufferSource, message)) {\n      valid = true;\n      break;\n    }\n  }\n  if (!valid) {\n    throw new WebhookVerificationError('Webhook signature verification failed.', 'invalid_signature');\n  }\n\n  let event: XModeWebhookEvent;\n  try {\n    event = JSON.parse(payload) as XModeWebhookEvent;\n  } catch {\n    throw new WebhookVerificationError('Webhook payload is not valid JSON.', 'malformed');\n  }\n\n  return { event, requestId: getHeader(headers, 'x-xmode-request-id'), timestamp };\n}\n\n/** True when the event is a video record (image records carry `referencesCount`). */\nexport function isVideoEvent(event: XModeWebhookEvent): event is VideoRecord {\n  return !('referencesCount' in event);\n}\n\n/** True when the event is an image generation record. */\nexport function isGenerationEvent(event: XModeWebhookEvent): event is GenerationRecord {\n  return 'referencesCount' in event;\n}\n"],"mappings":";;AAmBA,IAAa,2BAAb,cAA8C,MAAM;CAClD;CACA,YAAY,SAAiB,QAAmC;EAC9D,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,SAAS;CAChB;AACF;AA0BA,MAAM,UAAU,IAAI,YAAY;AAChC,MAAM,4BAA4B;AAElC,SAAS,UAAU,SAAsB,MAA6B;CACpE,IAAI,OAAO,YAAY,eAAe,mBAAmB,SACvD,OAAO,QAAQ,IAAI,IAAI;CAEzB,MAAM,SAAS,KAAK,YAAY;CAChC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,GAC/C,IAAI,IAAI,YAAY,MAAM,QAAQ;EAChC,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO,MAAM,MAAM;EAC7C,OAAO,SAAS;CAClB;CAEF,OAAO;AACT;AAEA,SAAS,WAAW,KAAgC;CAClD,IAAI,IAAI,WAAW,KAAK,IAAI,SAAS,MAAM,KAAK,eAAe,KAAK,GAAG,GAAG,OAAO;CACjF,MAAM,QAAQ,IAAI,WAAW,IAAI,SAAS,CAAC;CAC3C,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAChC,MAAM,KAAK,OAAO,SAAS,IAAI,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE;CAE5D,OAAO;AACT;;;;;;;;;;AAWA,eAAsB,cAAc,SAAyD;CAC3F,MAAM,EAAE,SAAS,SAAS,WAAW;CACrC,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,MAAM,QAAQ,OAAO,KAAK;CAEhC,MAAM,kBAAkB,UAAU,SAAS,mBAAmB;CAC9D,MAAM,kBAAkB,UAAU,SAAS,mBAAmB;CAC9D,IAAI,CAAC,mBAAmB,CAAC,iBACvB,MAAM,IAAI,yBACR,0DACA,gBACF;CAGF,MAAM,YAAY,OAAO,eAAe;CACxC,IAAI,CAAC,OAAO,SAAS,SAAS,GAC5B,MAAM,IAAI,yBAAyB,uCAAuC,WAAW;CAEvF,IAAI,KAAK,IAAI,IAAI,IAAI,MAAO,SAAS,IAAI,WACvC,MAAM,IAAI,yBACR,uDACA,4BACF;CAIF,MAAM,aAAa,gBAChB,MAAM,QAAQ,CAAC,CACf,QAAQ,SAAS,KAAK,WAAW,KAAK,CAAC,CAAC,CACxC,KAAK,SAAS,KAAK,MAAM,CAAC,CAAC;CAC9B,IAAI,WAAW,WAAW,GACxB,MAAM,IAAI,yBAAyB,oCAAoC,WAAW;CAGpF,MAAM,MAAM,MAAM,OAAO,OAAO,UAC9B,OACA,QAAQ,OAAO,MAAM,GACrB;EAAE,MAAM;EAAQ,MAAM;CAAU,GAChC,OACA,CAAC,QAAQ,CACX;CAGA,MAAM,UAAU,QAAQ,OAAO,GAAG,gBAAgB,GAAG,SAAS;CAE9D,IAAI,QAAQ;CACZ,KAAK,MAAM,OAAO,YAAY;EAC5B,MAAM,iBAAiB,WAAW,GAAG;EACrC,IAAI,CAAC,gBAAgB;EAErB,IAAI,MAAM,OAAO,OAAO,OAAO,QAAQ,KAAK,gBAAgC,OAAO,GAAG;GACpF,QAAQ;GACR;EACF;CACF;CACA,IAAI,CAAC,OACH,MAAM,IAAI,yBAAyB,0CAA0C,mBAAmB;CAGlG,IAAI;CACJ,IAAI;EACF,QAAQ,KAAK,MAAM,OAAO;CAC5B,QAAQ;EACN,MAAM,IAAI,yBAAyB,sCAAsC,WAAW;CACtF;CAEA,OAAO;EAAE;EAAO,WAAW,UAAU,SAAS,oBAAoB;EAAG;CAAU;AACjF;;AAGA,SAAgB,aAAa,OAAgD;CAC3E,OAAO,EAAE,qBAAqB;AAChC;;AAGA,SAAgB,kBAAkB,OAAqD;CACrF,OAAO,qBAAqB;AAC9B"}

package/dist/webhooks.d.cts

@@ -0,0 +1,45 @@
+import { K as VideoRecord, T as GenerationRecord } from "./types-BLVayOx3.cjs";
+
+//#region src/webhooks.d.ts
+type WebhookVerificationReason = 'missing_header' | 'invalid_signature' | 'timestamp_out_of_tolerance' | 'malformed';
+declare class WebhookVerificationError extends Error {
+  readonly reason: WebhookVerificationReason;
+  constructor(message: string, reason: WebhookVerificationReason);
+}
+/** The webhook body is the same shape as `generations.get` / `videos.get`. */
+type XModeWebhookEvent = GenerationRecord | VideoRecord;
+type HeadersLike = Headers | Record<string, string | string[] | undefined>;
+interface VerifyWebhookOptions {
+  /** The RAW request body string. Must NOT be a re-serialized object. */
+  payload: string;
+  /** Request headers, as a `Headers` object or a plain record. */
+  headers: HeadersLike;
+  /** Your account webhook signing secret. */
+  secret: string;
+  /** Allowed clock skew in seconds. Defaults to 300 (5 minutes). */
+  tolerance?: number;
+  /** Clock injection for tests; returns ms since epoch. Defaults to `Date.now`. */
+  now?: () => number;
+}
+interface VerifiedWebhook {
+  event: XModeWebhookEvent;
+  requestId: string | null;
+  timestamp: number;
+}
+/**
+ * Verify a webhook delivery and parse its body. Resolves with the typed event,
+ * or throws {@link WebhookVerificationError} (with a `reason`) on any failure.
+ *
+ * ```ts
+ * import { verifyWebhook } from '@xmodeai/sdk/webhooks';
+ * const { event } = await verifyWebhook({ payload: rawBody, headers: req.headers, secret });
+ * ```
+ */
+declare function verifyWebhook(options: VerifyWebhookOptions): Promise<VerifiedWebhook>;
+/** True when the event is a video record (image records carry `referencesCount`). */
+declare function isVideoEvent(event: XModeWebhookEvent): event is VideoRecord;
+/** True when the event is an image generation record. */
+declare function isGenerationEvent(event: XModeWebhookEvent): event is GenerationRecord;
+//#endregion
+export { HeadersLike, VerifiedWebhook, VerifyWebhookOptions, WebhookVerificationError, WebhookVerificationReason, XModeWebhookEvent, isGenerationEvent, isVideoEvent, verifyWebhook };
+//# sourceMappingURL=webhooks.d.cts.map

package/dist/webhooks.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.cts","names":[],"sources":["../src/webhooks.ts"],"mappings":";;;KAaY,yBAAA;AAAA,cAMC,wBAAA,SAAiC,KAAA;EAAA,SACnC,MAAA,EAAQ,yBAAA;cACL,OAAA,UAAiB,MAAA,EAAQ,yBAAA;AAAA;;KAQ3B,iBAAA,GAAoB,gBAAA,GAAmB,WAAW;AAAA,KAElD,WAAA,GAAc,OAAA,GAAU,MAAM;AAAA,UAEzB,oBAAA;EAZsB;EAcrC,OAAA;EAd8D;EAgB9D,OAAA,EAAS,WAAW;EARV;EAUV,MAAA;;EAEA,SAAA;EAZ4D;EAc5D,GAAA;AAAA;AAAA,UAGe,eAAA;EACf,KAAA,EAAO,iBAAiB;EACxB,SAAA;EACA,SAAA;AAAA;;;;;;;;;;iBAsCoB,aAAA,CAAc,OAAA,EAAS,oBAAA,GAAuB,OAAA,CAAQ,eAAA;AAzC5E;AAAA,iBA+GgB,YAAA,CAAa,KAAA,EAAO,iBAAA,GAAoB,KAAA,IAAS,WAAW;;iBAK5D,iBAAA,CAAkB,KAAA,EAAO,iBAAA,GAAoB,KAAA,IAAS,gBAAgB"}

package/dist/webhooks.d.ts

@@ -0,0 +1,45 @@
+import { K as VideoRecord, T as GenerationRecord } from "./types-BLVayOx3.js";
+
+//#region src/webhooks.d.ts
+type WebhookVerificationReason = 'missing_header' | 'invalid_signature' | 'timestamp_out_of_tolerance' | 'malformed';
+declare class WebhookVerificationError extends Error {
+  readonly reason: WebhookVerificationReason;
+  constructor(message: string, reason: WebhookVerificationReason);
+}
+/** The webhook body is the same shape as `generations.get` / `videos.get`. */
+type XModeWebhookEvent = GenerationRecord | VideoRecord;
+type HeadersLike = Headers | Record<string, string | string[] | undefined>;
+interface VerifyWebhookOptions {
+  /** The RAW request body string. Must NOT be a re-serialized object. */
+  payload: string;
+  /** Request headers, as a `Headers` object or a plain record. */
+  headers: HeadersLike;
+  /** Your account webhook signing secret. */
+  secret: string;
+  /** Allowed clock skew in seconds. Defaults to 300 (5 minutes). */
+  tolerance?: number;
+  /** Clock injection for tests; returns ms since epoch. Defaults to `Date.now`. */
+  now?: () => number;
+}
+interface VerifiedWebhook {
+  event: XModeWebhookEvent;
+  requestId: string | null;
+  timestamp: number;
+}
+/**
+ * Verify a webhook delivery and parse its body. Resolves with the typed event,
+ * or throws {@link WebhookVerificationError} (with a `reason`) on any failure.
+ *
+ * ```ts
+ * import { verifyWebhook } from '@xmodeai/sdk/webhooks';
+ * const { event } = await verifyWebhook({ payload: rawBody, headers: req.headers, secret });
+ * ```
+ */
+declare function verifyWebhook(options: VerifyWebhookOptions): Promise<VerifiedWebhook>;
+/** True when the event is a video record (image records carry `referencesCount`). */
+declare function isVideoEvent(event: XModeWebhookEvent): event is VideoRecord;
+/** True when the event is an image generation record. */
+declare function isGenerationEvent(event: XModeWebhookEvent): event is GenerationRecord;
+//#endregion
+export { HeadersLike, VerifiedWebhook, VerifyWebhookOptions, WebhookVerificationError, WebhookVerificationReason, XModeWebhookEvent, isGenerationEvent, isVideoEvent, verifyWebhook };
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","names":[],"sources":["../src/webhooks.ts"],"mappings":";;;KAaY,yBAAA;AAAA,cAMC,wBAAA,SAAiC,KAAA;EAAA,SACnC,MAAA,EAAQ,yBAAA;cACL,OAAA,UAAiB,MAAA,EAAQ,yBAAA;AAAA;;KAQ3B,iBAAA,GAAoB,gBAAA,GAAmB,WAAW;AAAA,KAElD,WAAA,GAAc,OAAA,GAAU,MAAM;AAAA,UAEzB,oBAAA;EAZsB;EAcrC,OAAA;EAd8D;EAgB9D,OAAA,EAAS,WAAW;EARV;EAUV,MAAA;;EAEA,SAAA;EAZ4D;EAc5D,GAAA;AAAA;AAAA,UAGe,eAAA;EACf,KAAA,EAAO,iBAAiB;EACxB,SAAA;EACA,SAAA;AAAA;;;;;;;;;;iBAsCoB,aAAA,CAAc,OAAA,EAAS,oBAAA,GAAuB,OAAA,CAAQ,eAAA;AAzC5E;AAAA,iBA+GgB,YAAA,CAAa,KAAA,EAAO,iBAAA,GAAoB,KAAA,IAAS,WAAW;;iBAK5D,iBAAA,CAAkB,KAAA,EAAO,iBAAA,GAAoB,KAAA,IAAS,gBAAgB"}

package/dist/webhooks.js

@@ -0,0 +1,86 @@
+//#region src/webhooks.ts
+var WebhookVerificationError = class extends Error {
+	reason;
+	constructor(message, reason) {
+		super(message);
+		this.name = "WebhookVerificationError";
+		this.reason = reason;
+	}
+};
+const encoder = new TextEncoder();
+const DEFAULT_TOLERANCE_SECONDS = 300;
+function getHeader(headers, name) {
+	if (typeof Headers !== "undefined" && headers instanceof Headers) return headers.get(name);
+	const target = name.toLowerCase();
+	for (const [key, value] of Object.entries(headers)) if (key.toLowerCase() === target) {
+		if (Array.isArray(value)) return value[0] ?? null;
+		return value ?? null;
+	}
+	return null;
+}
+function hexToBytes(hex) {
+	if (hex.length === 0 || hex.length % 2 !== 0 || /[^0-9a-fA-F]/.test(hex)) return null;
+	const bytes = new Uint8Array(hex.length / 2);
+	for (let i = 0; i < bytes.length; i++) bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+	return bytes;
+}
+/**
+* Verify a webhook delivery and parse its body. Resolves with the typed event,
+* or throws {@link WebhookVerificationError} (with a `reason`) on any failure.
+*
+* ```ts
+* import { verifyWebhook } from '@xmodeai/sdk/webhooks';
+* const { event } = await verifyWebhook({ payload: rawBody, headers: req.headers, secret });
+* ```
+*/
+async function verifyWebhook(options) {
+	const { payload, headers, secret } = options;
+	const tolerance = options.tolerance ?? DEFAULT_TOLERANCE_SECONDS;
+	const now = options.now ?? Date.now;
+	const signatureHeader = getHeader(headers, "x-xmode-signature");
+	const timestampHeader = getHeader(headers, "x-xmode-timestamp");
+	if (!signatureHeader || !timestampHeader) throw new WebhookVerificationError("Missing X-XMode-Signature or X-XMode-Timestamp header.", "missing_header");
+	const timestamp = Number(timestampHeader);
+	if (!Number.isFinite(timestamp)) throw new WebhookVerificationError("Malformed X-XMode-Timestamp header.", "malformed");
+	if (Math.abs(now() / 1e3 - timestamp) > tolerance) throw new WebhookVerificationError("Webhook timestamp is outside the allowed tolerance.", "timestamp_out_of_tolerance");
+	const candidates = signatureHeader.split(/[,\s]+/).filter((part) => part.startsWith("v1=")).map((part) => part.slice(3));
+	if (candidates.length === 0) throw new WebhookVerificationError("No v1 signature found in header.", "malformed");
+	const key = await crypto.subtle.importKey("raw", encoder.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["verify"]);
+	const message = encoder.encode(`${timestampHeader}.${payload}`);
+	let valid = false;
+	for (const hex of candidates) {
+		const signatureBytes = hexToBytes(hex);
+		if (!signatureBytes) continue;
+		if (await crypto.subtle.verify("HMAC", key, signatureBytes, message)) {
+			valid = true;
+			break;
+		}
+	}
+	if (!valid) throw new WebhookVerificationError("Webhook signature verification failed.", "invalid_signature");
+	let event;
+	try {
+		event = JSON.parse(payload);
+	} catch {
+		throw new WebhookVerificationError("Webhook payload is not valid JSON.", "malformed");
+	}
+	return {
+		event,
+		requestId: getHeader(headers, "x-xmode-request-id"),
+		timestamp
+	};
+}
+/** True when the event is a video record (image records carry `referencesCount`). */
+function isVideoEvent(event) {
+	return !("referencesCount" in event);
+}
+/** True when the event is an image generation record. */
+function isGenerationEvent(event) {
+	return "referencesCount" in event;
+}
+//#endregion
+export { WebhookVerificationError, isGenerationEvent, isVideoEvent, verifyWebhook };
+
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","names":[],"sources":["../src/webhooks.ts"],"sourcesContent":["/**\n * Webhook verification — published at the `@xmodeai/sdk/webhooks` subpath.\n *\n * Uses Web Crypto (`crypto.subtle`) only, so it runs unchanged on Node 18+,\n * Deno, Bun, Cloudflare Workers and other edge runtimes without `node:crypto`.\n *\n * Outbound signature contract (what xMode sends):\n *   X-XMode-Signature:  v1=<hex(HMAC_SHA256(secret, \"<timestamp>.<rawBody>\"))>\n *   X-XMode-Timestamp:  unix seconds when the payload was built\n *   X-XMode-Request-Id: requestId (handy for client-side dedup)\n */\nimport type { GenerationRecord, VideoRecord } from './types';\n\nexport type WebhookVerificationReason =\n  | 'missing_header'\n  | 'invalid_signature'\n  | 'timestamp_out_of_tolerance'\n  | 'malformed';\n\nexport class WebhookVerificationError extends Error {\n  readonly reason: WebhookVerificationReason;\n  constructor(message: string, reason: WebhookVerificationReason) {\n    super(message);\n    this.name = 'WebhookVerificationError';\n    this.reason = reason;\n  }\n}\n\n/** The webhook body is the same shape as `generations.get` / `videos.get`. */\nexport type XModeWebhookEvent = GenerationRecord | VideoRecord;\n\nexport type HeadersLike = Headers | Record<string, string | string[] | undefined>;\n\nexport interface VerifyWebhookOptions {\n  /** The RAW request body string. Must NOT be a re-serialized object. */\n  payload: string;\n  /** Request headers, as a `Headers` object or a plain record. */\n  headers: HeadersLike;\n  /** Your account webhook signing secret. */\n  secret: string;\n  /** Allowed clock skew in seconds. Defaults to 300 (5 minutes). */\n  tolerance?: number;\n  /** Clock injection for tests; returns ms since epoch. Defaults to `Date.now`. */\n  now?: () => number;\n}\n\nexport interface VerifiedWebhook {\n  event: XModeWebhookEvent;\n  requestId: string | null;\n  timestamp: number;\n}\n\nconst encoder = new TextEncoder();\nconst DEFAULT_TOLERANCE_SECONDS = 300;\n\nfunction getHeader(headers: HeadersLike, name: string): string | null {\n  if (typeof Headers !== 'undefined' && headers instanceof Headers) {\n    return headers.get(name);\n  }\n  const target = name.toLowerCase();\n  for (const [key, value] of Object.entries(headers)) {\n    if (key.toLowerCase() === target) {\n      if (Array.isArray(value)) return value[0] ?? null;\n      return value ?? null;\n    }\n  }\n  return null;\n}\n\nfunction hexToBytes(hex: string): Uint8Array | null {\n  if (hex.length === 0 || hex.length % 2 !== 0 || /[^0-9a-fA-F]/.test(hex)) return null;\n  const bytes = new Uint8Array(hex.length / 2);\n  for (let i = 0; i < bytes.length; i++) {\n    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);\n  }\n  return bytes;\n}\n\n/**\n * Verify a webhook delivery and parse its body. Resolves with the typed event,\n * or throws {@link WebhookVerificationError} (with a `reason`) on any failure.\n *\n * ```ts\n * import { verifyWebhook } from '@xmodeai/sdk/webhooks';\n * const { event } = await verifyWebhook({ payload: rawBody, headers: req.headers, secret });\n * ```\n */\nexport async function verifyWebhook(options: VerifyWebhookOptions): Promise<VerifiedWebhook> {\n  const { payload, headers, secret } = options;\n  const tolerance = options.tolerance ?? DEFAULT_TOLERANCE_SECONDS;\n  const now = options.now ?? Date.now;\n\n  const signatureHeader = getHeader(headers, 'x-xmode-signature');\n  const timestampHeader = getHeader(headers, 'x-xmode-timestamp');\n  if (!signatureHeader || !timestampHeader) {\n    throw new WebhookVerificationError(\n      'Missing X-XMode-Signature or X-XMode-Timestamp header.',\n      'missing_header',\n    );\n  }\n\n  const timestamp = Number(timestampHeader);\n  if (!Number.isFinite(timestamp)) {\n    throw new WebhookVerificationError('Malformed X-XMode-Timestamp header.', 'malformed');\n  }\n  if (Math.abs(now() / 1000 - timestamp) > tolerance) {\n    throw new WebhookVerificationError(\n      'Webhook timestamp is outside the allowed tolerance.',\n      'timestamp_out_of_tolerance',\n    );\n  }\n\n  // Header is `v1=<hex>`; tolerate several space/comma-separated entries (rotation).\n  const candidates = signatureHeader\n    .split(/[,\\s]+/)\n    .filter((part) => part.startsWith('v1='))\n    .map((part) => part.slice(3));\n  if (candidates.length === 0) {\n    throw new WebhookVerificationError('No v1 signature found in header.', 'malformed');\n  }\n\n  const key = await crypto.subtle.importKey(\n    'raw',\n    encoder.encode(secret) as BufferSource,\n    { name: 'HMAC', hash: 'SHA-256' },\n    false,\n    ['verify'],\n  );\n  // Sign over the RAW timestamp header, not the parsed number, so verification\n  // never depends on the server using a canonical integer representation.\n  const message = encoder.encode(`${timestampHeader}.${payload}`) as BufferSource;\n\n  let valid = false;\n  for (const hex of candidates) {\n    const signatureBytes = hexToBytes(hex);\n    if (!signatureBytes) continue;\n    // crypto.subtle.verify is constant-time internally.\n    if (await crypto.subtle.verify('HMAC', key, signatureBytes as BufferSource, message)) {\n      valid = true;\n      break;\n    }\n  }\n  if (!valid) {\n    throw new WebhookVerificationError('Webhook signature verification failed.', 'invalid_signature');\n  }\n\n  let event: XModeWebhookEvent;\n  try {\n    event = JSON.parse(payload) as XModeWebhookEvent;\n  } catch {\n    throw new WebhookVerificationError('Webhook payload is not valid JSON.', 'malformed');\n  }\n\n  return { event, requestId: getHeader(headers, 'x-xmode-request-id'), timestamp };\n}\n\n/** True when the event is a video record (image records carry `referencesCount`). */\nexport function isVideoEvent(event: XModeWebhookEvent): event is VideoRecord {\n  return !('referencesCount' in event);\n}\n\n/** True when the event is an image generation record. */\nexport function isGenerationEvent(event: XModeWebhookEvent): event is GenerationRecord {\n  return 'referencesCount' in event;\n}\n"],"mappings":";AAmBA,IAAa,2BAAb,cAA8C,MAAM;CAClD;CACA,YAAY,SAAiB,QAAmC;EAC9D,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,SAAS;CAChB;AACF;AA0BA,MAAM,UAAU,IAAI,YAAY;AAChC,MAAM,4BAA4B;AAElC,SAAS,UAAU,SAAsB,MAA6B;CACpE,IAAI,OAAO,YAAY,eAAe,mBAAmB,SACvD,OAAO,QAAQ,IAAI,IAAI;CAEzB,MAAM,SAAS,KAAK,YAAY;CAChC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,GAC/C,IAAI,IAAI,YAAY,MAAM,QAAQ;EAChC,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO,MAAM,MAAM;EAC7C,OAAO,SAAS;CAClB;CAEF,OAAO;AACT;AAEA,SAAS,WAAW,KAAgC;CAClD,IAAI,IAAI,WAAW,KAAK,IAAI,SAAS,MAAM,KAAK,eAAe,KAAK,GAAG,GAAG,OAAO;CACjF,MAAM,QAAQ,IAAI,WAAW,IAAI,SAAS,CAAC;CAC3C,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAChC,MAAM,KAAK,OAAO,SAAS,IAAI,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE;CAE5D,OAAO;AACT;;;;;;;;;;AAWA,eAAsB,cAAc,SAAyD;CAC3F,MAAM,EAAE,SAAS,SAAS,WAAW;CACrC,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,MAAM,QAAQ,OAAO,KAAK;CAEhC,MAAM,kBAAkB,UAAU,SAAS,mBAAmB;CAC9D,MAAM,kBAAkB,UAAU,SAAS,mBAAmB;CAC9D,IAAI,CAAC,mBAAmB,CAAC,iBACvB,MAAM,IAAI,yBACR,0DACA,gBACF;CAGF,MAAM,YAAY,OAAO,eAAe;CACxC,IAAI,CAAC,OAAO,SAAS,SAAS,GAC5B,MAAM,IAAI,yBAAyB,uCAAuC,WAAW;CAEvF,IAAI,KAAK,IAAI,IAAI,IAAI,MAAO,SAAS,IAAI,WACvC,MAAM,IAAI,yBACR,uDACA,4BACF;CAIF,MAAM,aAAa,gBAChB,MAAM,QAAQ,CAAC,CACf,QAAQ,SAAS,KAAK,WAAW,KAAK,CAAC,CAAC,CACxC,KAAK,SAAS,KAAK,MAAM,CAAC,CAAC;CAC9B,IAAI,WAAW,WAAW,GACxB,MAAM,IAAI,yBAAyB,oCAAoC,WAAW;CAGpF,MAAM,MAAM,MAAM,OAAO,OAAO,UAC9B,OACA,QAAQ,OAAO,MAAM,GACrB;EAAE,MAAM;EAAQ,MAAM;CAAU,GAChC,OACA,CAAC,QAAQ,CACX;CAGA,MAAM,UAAU,QAAQ,OAAO,GAAG,gBAAgB,GAAG,SAAS;CAE9D,IAAI,QAAQ;CACZ,KAAK,MAAM,OAAO,YAAY;EAC5B,MAAM,iBAAiB,WAAW,GAAG;EACrC,IAAI,CAAC,gBAAgB;EAErB,IAAI,MAAM,OAAO,OAAO,OAAO,QAAQ,KAAK,gBAAgC,OAAO,GAAG;GACpF,QAAQ;GACR;EACF;CACF;CACA,IAAI,CAAC,OACH,MAAM,IAAI,yBAAyB,0CAA0C,mBAAmB;CAGlG,IAAI;CACJ,IAAI;EACF,QAAQ,KAAK,MAAM,OAAO;CAC5B,QAAQ;EACN,MAAM,IAAI,yBAAyB,sCAAsC,WAAW;CACtF;CAEA,OAAO;EAAE;EAAO,WAAW,UAAU,SAAS,oBAAoB;EAAG;CAAU;AACjF;;AAGA,SAAgB,aAAa,OAAgD;CAC3E,OAAO,EAAE,qBAAqB;AAChC;;AAGA,SAAgB,kBAAkB,OAAqD;CACrF,OAAO,qBAAqB;AAC9B"}