@mystars-tg/faas-sdk 0.1.2

package/dist/index.js

@@ -0,0 +1,1460 @@
+// src/errors.ts
+var MyStarsError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var MyStarsApiError = class extends MyStarsError {
+  /** The envelope `error.code`, or `"unknown"` / `"network"`. */
+  code;
+  /** HTTP status code (`0` for a network/timeout failure). */
+  status;
+  /** Buyer-facing Telegram/Fragment message, when the server supplied one. */
+  telegramMessage;
+  /** The `x-request-id` response header, when present. */
+  requestId;
+  /** Coarse hint that the failure is potentially transient. The retry policy decides for real. */
+  retryable;
+  /** The parsed response body (or the thrown error), for debugging. */
+  raw;
+  /**
+   * The `Idempotency-Key` that was sent with the request that failed, when known.
+   *
+   * `createOrder` stamps this on a thrown error so you can SAFELY retry the
+   * create with the SAME key (`{ idempotencyKey: err.idempotencyKey }`) instead
+   * of minting a duplicate deliverable when you can't tell whether the order was
+   * created server-side. `undefined` for errors not raised by a keyed request.
+   */
+  idempotencyKey;
+  constructor(init) {
+    super(init.message);
+    this.code = init.code;
+    this.status = init.status;
+    this.telegramMessage = init.telegramMessage;
+    this.requestId = init.requestId;
+    this.retryable = init.retryable ?? false;
+    this.raw = init.raw;
+    this.idempotencyKey = init.idempotencyKey;
+  }
+};
+var BadRequestError = class extends MyStarsApiError {
+};
+var UnauthorizedError = class extends MyStarsApiError {
+};
+var ForbiddenError = class extends MyStarsApiError {
+};
+var NotFoundError = class extends MyStarsApiError {
+};
+var ConflictError = class extends MyStarsApiError {
+};
+var IdempotencyConflictError = class extends ConflictError {
+};
+var OrderNotCancellableError = class extends ConflictError {
+};
+var RecipientIneligibleError = class extends MyStarsApiError {
+  telegramMessage;
+  constructor(init) {
+    super(init);
+    this.telegramMessage = init.telegramMessage ?? init.message;
+  }
+};
+var RateLimitError = class extends MyStarsApiError {
+  /** Milliseconds to wait before retrying, from `Retry-After`; `null` for the order-cap/flood limiter. */
+  retryAfterMs;
+  limit;
+  remaining;
+  reset;
+  /** `"general"` when RFC-9110 `RateLimit-*` headers are present; `"order_cap"` otherwise. */
+  kind;
+  constructor(init) {
+    super(init);
+    this.retryAfterMs = init.retryAfterMs ?? null;
+    this.limit = init.limit ?? null;
+    this.remaining = init.remaining ?? null;
+    this.reset = init.reset ?? null;
+    this.kind = init.kind;
+  }
+};
+var ServiceUnavailableError = class extends MyStarsApiError {
+};
+var InternalServerError = class extends MyStarsApiError {
+};
+var NetworkError = class extends MyStarsApiError {
+};
+var TimeoutError = class extends NetworkError {
+};
+var WebhookSignatureError = class extends MyStarsError {
+};
+var OrderWaitTimeoutError = class extends MyStarsError {
+  /** The most recent order snapshot observed before timing out. */
+  lastOrder;
+  constructor(lastOrder, message) {
+    super(message ?? `order ${lastOrder.order_id} did not finish in time (last status: ${lastOrder.status})`);
+    this.lastOrder = lastOrder;
+  }
+};
+function header(headers, name) {
+  const v = headers.get(name);
+  return v === null ? void 0 : v;
+}
+function toInt(value) {
+  if (value === void 0) return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+function parseRetryAfterMs(value, now = Date.now()) {
+  if (value === void 0) return null;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return Math.max(0, Math.round(seconds * 1e3));
+  const date = Date.parse(value);
+  if (Number.isFinite(date)) return Math.max(0, date - now);
+  return null;
+}
+function parseEnvelope(status, body) {
+  if (body && typeof body === "object" && "error" in body) {
+    const err = body.error;
+    if (err && typeof err === "object") {
+      const e = err;
+      return {
+        code: typeof e.code === "string" ? e.code : "unknown",
+        message: typeof e.message === "string" ? e.message : `HTTP ${status}`,
+        telegramMessage: typeof e.telegram_message === "string" ? e.telegram_message : void 0
+      };
+    }
+    if (typeof err === "string") {
+      return { code: err, message: err };
+    }
+  }
+  return { code: "unknown", message: `HTTP ${status}` };
+}
+function errorFromResponse(status, body, headers) {
+  const { code, message, telegramMessage } = parseEnvelope(status, body);
+  const requestId = header(headers, "x-request-id");
+  const base = { code, status, message, telegramMessage, requestId, raw: body };
+  switch (status) {
+    case 400:
+      return new BadRequestError(base);
+    case 401:
+      return new UnauthorizedError(base);
+    case 403:
+      return new ForbiddenError(base);
+    case 404:
+      return new NotFoundError(base);
+    case 409: {
+      const m = message.toLowerCase();
+      if (m.includes("idempotency")) return new IdempotencyConflictError(base);
+      if (m.includes("cancel")) return new OrderNotCancellableError(base);
+      return new ConflictError(base);
+    }
+    case 422:
+      return new RecipientIneligibleError(base);
+    case 429: {
+      const limit = toInt(header(headers, "ratelimit-limit"));
+      const remaining = toInt(header(headers, "ratelimit-remaining"));
+      const reset = toInt(header(headers, "ratelimit-reset"));
+      const retryAfterMs = parseRetryAfterMs(header(headers, "retry-after"));
+      const kind = limit !== null || retryAfterMs !== null ? "general" : "order_cap";
+      return new RateLimitError({
+        ...base,
+        retryable: kind === "general",
+        retryAfterMs,
+        limit,
+        remaining,
+        reset,
+        kind
+      });
+    }
+    case 503:
+      return new ServiceUnavailableError({ ...base, retryable: true });
+    case 500:
+      return new InternalServerError({ ...base, retryable: true });
+    default:
+      return new MyStarsApiError({ ...base, retryable: status >= 500 });
+  }
+}
+
+// src/internal/sleep.ts
+function defaultSleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error("aborted"));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new Error("aborted"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/http/retry.ts
+function defaultShouldRetry(ctx) {
+  if (!ctx.idempotent) return false;
+  const e = ctx.error;
+  if (e instanceof NetworkError) return true;
+  if (e instanceof ServiceUnavailableError) return true;
+  if (e instanceof InternalServerError) return true;
+  if (e instanceof RateLimitError) return e.kind === "general";
+  return e.retryable;
+}
+var DEFAULTS = {
+  maxRetries: 3,
+  baseDelayMs: 500,
+  maxDelayMs: 3e4,
+  jitter: "full",
+  respectRetryAfter: true,
+  retryOn: defaultShouldRetry
+};
+function resolveRetryPolicy(policy) {
+  if (policy === false) return { ...DEFAULTS, maxRetries: 0 };
+  if (!policy) return DEFAULTS;
+  return {
+    maxRetries: policy.maxRetries ?? DEFAULTS.maxRetries,
+    baseDelayMs: policy.baseDelayMs ?? DEFAULTS.baseDelayMs,
+    maxDelayMs: policy.maxDelayMs ?? DEFAULTS.maxDelayMs,
+    jitter: policy.jitter ?? DEFAULTS.jitter,
+    respectRetryAfter: policy.respectRetryAfter ?? DEFAULTS.respectRetryAfter,
+    retryOn: policy.retryOn ?? DEFAULTS.retryOn
+  };
+}
+function computeDelayMs(ctx, policy, random = Math.random) {
+  const exp = policy.baseDelayMs * 2 ** ctx.attempt;
+  const capped = Math.min(exp, policy.maxDelayMs);
+  let delay = policy.jitter === "full" ? random() * capped : capped;
+  if (policy.respectRetryAfter && ctx.error instanceof RateLimitError && ctx.error.retryAfterMs !== null) {
+    delay = Math.max(delay, Math.min(ctx.error.retryAfterMs, policy.maxDelayMs));
+  }
+  return Math.round(delay);
+}
+
+// src/http/transport.ts
+var MAX_RESPONSE_BYTES = 4e6;
+function buildUrl(baseUrl, path, query) {
+  const base = baseUrl.replace(/\/+$/, "");
+  const suffix = path.startsWith("/") ? path : `/${path}`;
+  let url = `${base}${suffix}`;
+  if (query) {
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== void 0) params.set(k, String(v));
+    }
+    const qs = params.toString();
+    if (qs) url += `?${qs}`;
+  }
+  return url;
+}
+async function readJson(res) {
+  const text = await readBoundedText(res);
+  if (text.length === 0) return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new MyStarsApiError({
+      code: "invalid_response",
+      status: res.status,
+      message: `Response was not valid JSON (HTTP ${res.status})`,
+      // A 5xx with an HTML body (Cloudflare/nginx gateway page) is transient → retryable;
+      // a 2xx with malformed JSON is not (retrying won't fix a bad success body).
+      retryable: res.status >= 500,
+      raw: text.slice(0, 500)
+    });
+  }
+}
+async function readBoundedText(res) {
+  const body = res.body;
+  if (!body || typeof body.getReader !== "function") {
+    const text = await res.text();
+    if (text.length > MAX_RESPONSE_BYTES) {
+      throw new MyStarsApiError({
+        code: "response_too_large",
+        status: res.status,
+        message: "Response body exceeded the size limit"
+      });
+    }
+    return text;
+  }
+  const reader = body.getReader();
+  const chunks = [];
+  let total = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value) {
+      total += value.byteLength;
+      if (total > MAX_RESPONSE_BYTES) {
+        await reader.cancel();
+        throw new MyStarsApiError({
+          code: "response_too_large",
+          status: res.status,
+          message: "Response body exceeded the size limit"
+        });
+      }
+      chunks.push(value);
+    }
+  }
+  return new TextDecoder().decode(concat(chunks, total));
+}
+function concat(chunks, total) {
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.byteLength;
+  }
+  return out;
+}
+var Transport = class {
+  opts;
+  sleep;
+  random;
+  constructor(opts) {
+    this.opts = opts;
+    this.sleep = opts.sleep ?? defaultSleep;
+    this.random = opts.random ?? Math.random;
+  }
+  async request(params) {
+    const url = buildUrl(this.opts.baseUrl, params.path, params.query);
+    const idempotent = params.idempotent ?? (params.method === "GET" || params.idempotencyKey !== void 0);
+    const policy = this.opts.retry;
+    let attempt = 0;
+    for (; ; ) {
+      if (params.signal?.aborted) {
+        throw new NetworkError({ code: "aborted", status: 0, message: "request aborted by caller" });
+      }
+      try {
+        return await this.attempt(url, params);
+      } catch (err) {
+        const apiError = err instanceof MyStarsApiError ? err : wrapUnknown(err);
+        const ctx = { method: params.method, path: params.path, attempt, idempotent, error: apiError };
+        const willRetry = attempt < policy.maxRetries && !params.signal?.aborted && policy.retryOn(ctx);
+        if (!willRetry) throw apiError;
+        const delayMs = computeDelayMs(ctx, policy, this.random);
+        if (this.opts.interceptors?.onRetry) {
+          await this.opts.interceptors.onRetry({
+            method: params.method,
+            url,
+            attempt: attempt + 1,
+            delayMs,
+            reason: `${apiError.code} (HTTP ${apiError.status})`
+          });
+        }
+        await this.sleep(delayMs, params.signal);
+        attempt += 1;
+      }
+    }
+  }
+  async attempt(url, params) {
+    const headers = new Headers();
+    headers.set("Accept", "application/json");
+    headers.set("X-Api-Key", this.opts.apiKey);
+    if (this.opts.userAgent) headers.set("User-Agent", this.opts.userAgent);
+    if (params.idempotencyKey !== void 0) headers.set("Idempotency-Key", params.idempotencyKey);
+    let bodyText;
+    if (params.body !== void 0) {
+      headers.set("Content-Type", "application/json");
+      bodyText = JSON.stringify(params.body);
+    }
+    if (this.opts.interceptors?.onRequest) {
+      await this.opts.interceptors.onRequest({
+        method: params.method,
+        url,
+        idempotencyKey: params.idempotencyKey
+      });
+    }
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, this.opts.timeoutMs);
+    const onCallerAbort = () => controller.abort();
+    params.signal?.addEventListener("abort", onCallerAbort, { once: true });
+    const startedAt = Date.now();
+    let res;
+    let data;
+    try {
+      res = await this.opts.fetchImpl(url, {
+        method: params.method,
+        headers,
+        body: bodyText,
+        signal: controller.signal
+      });
+      data = await readJson(res);
+    } catch (err) {
+      if (timedOut) {
+        throw new TimeoutError({
+          code: "timeout",
+          status: 0,
+          message: `request timed out after ${this.opts.timeoutMs}ms`,
+          retryable: true
+        });
+      }
+      if (params.signal?.aborted) {
+        throw new NetworkError({ code: "aborted", status: 0, message: "request aborted by caller" });
+      }
+      if (err instanceof MyStarsApiError) throw err;
+      throw new NetworkError({
+        code: "network",
+        status: 0,
+        message: err instanceof Error ? err.message : "network request failed",
+        retryable: true,
+        raw: err
+      });
+    } finally {
+      clearTimeout(timer);
+      params.signal?.removeEventListener("abort", onCallerAbort);
+    }
+    const durationMs = Date.now() - startedAt;
+    const requestId = res.headers.get("x-request-id") ?? void 0;
+    if (this.opts.interceptors?.onResponse) {
+      await this.opts.interceptors.onResponse({
+        method: params.method,
+        url,
+        status: res.status,
+        durationMs,
+        requestId
+      });
+    }
+    if (!res.ok) {
+      throw errorFromResponse(res.status, data, res.headers);
+    }
+    return { status: res.status, data, headers: res.headers };
+  }
+};
+function wrapUnknown(err) {
+  return new NetworkError({
+    code: "network",
+    status: 0,
+    message: err instanceof Error ? err.message : "request failed",
+    retryable: true,
+    raw: err
+  });
+}
+
+// src/internal/uuid.ts
+var HEX = [];
+for (let i = 0; i < 256; i++) HEX.push((i + 256).toString(16).slice(1));
+function uuidv4() {
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === "function") {
+    return c.randomUUID();
+  }
+  const bytes = new Uint8Array(16);
+  if (c && typeof c.getRandomValues === "function") {
+    c.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256);
+  }
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = HEX;
+  const b = bytes;
+  return hex[b[0]] + hex[b[1]] + hex[b[2]] + hex[b[3]] + "-" + hex[b[4]] + hex[b[5]] + "-" + hex[b[6]] + hex[b[7]] + "-" + hex[b[8]] + hex[b[9]] + "-" + hex[b[10]] + hex[b[11]] + hex[b[12]] + hex[b[13]] + hex[b[14]] + hex[b[15]];
+}
+
+// src/internal/validate.ts
+var STARS_MIN_QUANTITY = 50;
+var STARS_MAX_QUANTITY = 1e6;
+var PREMIUM_MONTHS = [3, 6, 12];
+var USERNAME_RE = /^[a-z0-9_]{1,32}$/;
+var MyStarsValidationError = class extends MyStarsError {
+};
+function canonicalUsername(input) {
+  if (typeof input !== "string") {
+    throw new MyStarsValidationError("recipient username must be a string");
+  }
+  const canon = input.trim().replace(/^@+/, "").toLowerCase();
+  if (!USERNAME_RE.test(canon)) {
+    throw new MyStarsValidationError(
+      `invalid recipient username "${input}" \u2014 expected 1-32 chars of [a-z0-9_] (a leading @ is allowed)`
+    );
+  }
+  return canon;
+}
+function assertStarsQuantity(quantity) {
+  if (!Number.isInteger(quantity) || quantity < STARS_MIN_QUANTITY || quantity > STARS_MAX_QUANTITY) {
+    throw new MyStarsValidationError(
+      `stars quantity must be an integer in [${STARS_MIN_QUANTITY}, ${STARS_MAX_QUANTITY}], got ${quantity}`
+    );
+  }
+}
+function assertPremiumMonths(months) {
+  if (!PREMIUM_MONTHS.includes(months)) {
+    throw new MyStarsValidationError(
+      `premium months must be one of ${PREMIUM_MONTHS.join(", ")}, got ${months}`
+    );
+  }
+}
+function assertOrderType(type) {
+  if (type !== "stars" && type !== "premium") {
+    throw new MyStarsValidationError(`type must be "stars" or "premium", got ${String(type)}`);
+  }
+}
+
+// src/tracking/pager.ts
+var OrdersPager = class {
+  fetchPage;
+  startCursor;
+  /**
+   * @param fetchPage - fetches a page given a cursor (the client wires this to the transport)
+   * @param startCursor - an optional cursor to begin from (resumes mid-stream)
+   */
+  constructor(fetchPage, startCursor) {
+    this.fetchPage = fetchPage;
+    this.startCursor = startCursor;
+  }
+  /** Fetch a single page. Pass the previous page's `next_cursor` to advance. */
+  page(cursor) {
+    return this.fetchPage(cursor);
+  }
+  /** Yield one page at a time until `next_cursor` is null. */
+  async *pages() {
+    let cursor = this.startCursor;
+    for (; ; ) {
+      const page = await this.fetchPage(cursor);
+      yield page;
+      if (!page.next_cursor) break;
+      cursor = page.next_cursor;
+    }
+  }
+  /** Yield every order across all pages. */
+  async *[Symbol.asyncIterator]() {
+    for await (const page of this.pages()) {
+      for (const order of page.orders) yield order;
+    }
+  }
+  /** Collect every order across all pages into a single array. */
+  async all() {
+    const out = [];
+    for await (const order of this) out.push(order);
+    return out;
+  }
+};
+
+// src/types.ts
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "delivered",
+  "failed",
+  "reversed",
+  "expired",
+  "cancelled"
+]);
+function isTerminal(status) {
+  return TERMINAL_STATUSES.has(status);
+}
+var WEBHOOK_TERMINAL = /* @__PURE__ */ new Set([
+  "delivered",
+  "failed",
+  "reversed",
+  "expired"
+]);
+var INITIAL_ORDER_STATUS = "awaiting_payment";
+var CANCELLABLE_STATUSES = /* @__PURE__ */ new Set(["awaiting_payment"]);
+
+// src/tracking/reconcile.ts
+async function reconcile(client, opts) {
+  const sinceMs = opts.since !== void 0 ? new Date(opts.since).getTime() : void 0;
+  const missed = [];
+  for await (const order of client.listOrders({ status: opts.status, limit: opts.limit })) {
+    if (sinceMs !== void 0 && new Date(order.created_at).getTime() < sinceMs) break;
+    if (!isTerminal(order.status)) continue;
+    if (!await opts.isKnown(order)) {
+      missed.push(order);
+      await opts.onMissed?.(order);
+    }
+  }
+  return missed;
+}
+
+// src/tracking/waitForOrder.ts
+async function waitForOrder(orderId, options, deps) {
+  const pollIntervalMs = options.pollIntervalMs ?? 2e3;
+  const maxPollIntervalMs = options.maxPollIntervalMs ?? 15e3;
+  const backoffFactor = options.backoffFactor ?? 1.5;
+  const maxWaitMs = options.maxWaitMs ?? 30 * 60 * 1e3;
+  const jitter = options.jitter ?? "full";
+  const until = options.until ?? ((o) => isTerminal(o.status));
+  const deadline = deps.now() + maxWaitMs;
+  let interval = pollIntervalMs;
+  let lastStatus;
+  let lastOrder;
+  for (; ; ) {
+    lastOrder = await deps.getOrder(orderId, { signal: options.signal });
+    if (lastOrder.status !== lastStatus) {
+      lastStatus = lastOrder.status;
+      options.onUpdate?.(lastOrder);
+    }
+    if (until(lastOrder)) return lastOrder;
+    const remaining = deadline - deps.now();
+    if (remaining <= 0) throw new OrderWaitTimeoutError(lastOrder);
+    const base = Math.min(interval, maxPollIntervalMs);
+    const jittered = jitter === "full" ? base * (0.5 + 0.5 * deps.random()) : base;
+    await deps.sleep(Math.max(0, Math.min(jittered, remaining)), options.signal);
+    interval = Math.min(interval * backoffFactor, maxPollIntervalMs);
+  }
+}
+
+// src/version.ts
+var CONTRACT_VERSION = "1.9.0";
+var SDK_VERSION = "0.1.2";
+
+// src/client.ts
+var PRODUCTION_BASE_URL = "https://api.mystars.tg/v1";
+function resolveBaseUrl(opts) {
+  return opts.baseUrl ?? PRODUCTION_BASE_URL;
+}
+var MyStarsClient = class _MyStarsClient {
+  transport;
+  idempotencyKeyFactory;
+  now;
+  sleep;
+  random;
+  /**
+   * @param opts - the {@link MyStarsClientOptions} (at minimum `apiKey`). Prefer the
+   *   {@link MyStarsClient.production} factory.
+   * @throws `Error` if `apiKey` is missing, or no `fetch` is available (Node <18 — pass `fetch` explicitly)
+   */
+  constructor(opts) {
+    if (!opts.apiKey) throw new Error("MyStarsClient: `apiKey` is required");
+    const fetchImpl = opts.fetch ?? (globalThis.fetch ? globalThis.fetch.bind(globalThis) : void 0);
+    if (!fetchImpl) {
+      throw new Error("MyStarsClient: no global fetch found \u2014 pass `fetch` explicitly (Node <18 or a custom runtime)");
+    }
+    this.idempotencyKeyFactory = opts.idempotencyKeyFactory ?? uuidv4;
+    this.now = opts.now ?? (() => Date.now());
+    this.random = opts.random ?? Math.random;
+    this.sleep = opts.sleep ?? defaultSleep;
+    this.transport = new Transport({
+      apiKey: opts.apiKey,
+      baseUrl: resolveBaseUrl(opts),
+      fetchImpl,
+      timeoutMs: opts.timeoutMs ?? 3e4,
+      retry: resolveRetryPolicy(opts.retry),
+      userAgent: opts.userAgent ?? `mystars-faas-sdk/${SDK_VERSION}`,
+      interceptors: opts.interceptors,
+      sleep: opts.sleep,
+      random: opts.random
+    });
+  }
+  /**
+   * Build a client pointed at production (`api.mystars.tg`).
+   *
+   * @param apiKey - your tenant `faas_…` API key
+   * @param opts - any other {@link MyStarsClientOptions} except `apiKey`/`baseUrl`
+   * @returns a configured client
+   * @example
+   * ```ts
+   * const client = MyStarsClient.production(process.env.MYSTARS_API_KEY!);
+   * ```
+   */
+  static production(apiKey, opts) {
+    return new _MyStarsClient({ ...opts, apiKey });
+  }
+  /**
+   * `GET /v1/currencies` — the supported on-chain payment currencies.
+   *
+   * @param opts - optional `signal` to abort the request
+   * @returns the supported {@link CurrencyInfo} list
+   * @throws `MyStarsApiError` on an API/network failure
+   */
+  async listCurrencies(opts = {}) {
+    const { data } = await this.transport.request({
+      method: "GET",
+      path: "/currencies",
+      signal: opts.signal
+    });
+    return data.currencies;
+  }
+  /**
+   * `GET /v1/products` — the orderable product catalog (price-free).
+   *
+   * @param opts - optional `signal` to abort the request
+   * @returns the {@link Product} catalog (buyable shapes + limits)
+   * @throws `MyStarsApiError` on an API/network failure
+   */
+  async listProducts(opts = {}) {
+    const { data } = await this.transport.request({
+      method: "GET",
+      path: "/products",
+      signal: opts.signal
+    });
+    return data.products;
+  }
+  /**
+   * `GET /v1/pricing` — quote the all-in price for an item. Probe-rate-limited (30/min).
+   *
+   * @param params - `{ type, quantity | months, payment_currency? }`; `payment_currency` defaults server-side
+   * @param opts - optional `signal` to abort the request
+   * @returns the {@link PricingQuote} — `amount` is the all-in total in `currency`; `fee` is itemized for `usdt_ton`
+   * @throws `MyStarsValidationError` if `quantity`/`months` is out of range
+   * @throws `RateLimitError` (429) if the probe limit is exceeded
+   * @throws `ServiceUnavailableError` (503) if a price source is temporarily down
+   * @example
+   * ```ts
+   * const q = await client.getPricing({ type: "stars", quantity: 500, payment_currency: "ton" });
+   * console.log(`pay ${q.amount} ${q.currency}`);
+   * ```
+   */
+  async getPricing(params, opts = {}) {
+    assertOrderType(params.type);
+    const query = {
+      type: params.type,
+      payment_currency: params.payment_currency
+    };
+    if (params.type === "stars") {
+      assertStarsQuantity(params.quantity);
+      query.quantity = params.quantity;
+    } else {
+      assertPremiumMonths(params.months);
+      query.months = params.months;
+    }
+    const { data } = await this.transport.request({
+      method: "GET",
+      path: "/pricing",
+      query,
+      signal: opts.signal
+    });
+    return data;
+  }
+  /**
+   * `POST /v1/recipients/check` — resolve a `@username` and check eligibility before ordering.
+   *
+   * @param params - `{ type, recipient: { username }, months? }`; the username is canonicalized (strip `@`, lowercase)
+   * @param opts - optional `signal` to abort the request
+   * @returns the {@link RecipientCheck} — `resolved`/`eligible`, the display `recipient_name`, and a `reason` when ineligible
+   * @throws `MyStarsValidationError` if the username is malformed
+   * @throws `MyStarsApiError` on an API/network failure
+   */
+  async checkRecipient(params, opts = {}) {
+    assertOrderType(params.type);
+    const body = {
+      type: params.type,
+      recipient: { username: canonicalUsername(params.recipient.username) }
+    };
+    if (params.type === "premium" && params.months !== void 0) {
+      assertPremiumMonths(params.months);
+      body.months = params.months;
+    }
+    const { data } = await this.transport.request({
+      method: "POST",
+      path: "/recipients/check",
+      body,
+      // Read-only and fail-open server-side, so safe to retry on transient errors.
+      idempotent: true,
+      signal: opts.signal
+    });
+    return data;
+  }
+  /**
+   * `POST /v1/orders` — create an order. An `Idempotency-Key` is sent once and
+   * reused across this call's retries, so a retried create returns the idempotent
+   * replay (`replayed: true`) instead of a duplicate.
+   *
+   * MONEY SAFETY — supply a STABLE key derived from YOUR OWN order id
+   * (`{ idempotencyKey: \`order-\${myOrderId}\` }`). The auto-generated uuid only
+   * dedupes WITHIN a single `createOrder` call's internal retries; a brand-new
+   * call (e.g. your process crashed and re-ran) mints a fresh uuid and can create
+   * a SECOND order for the same intent. A caller-stable key makes the create
+   * idempotent across process restarts and at-least-once job runners.
+   *
+   * On failure the thrown {@link MyStarsApiError} carries the `idempotencyKey`
+   * that was used — when you can't tell whether the order was created
+   * server-side, retry with that exact key (`{ idempotencyKey: err.idempotencyKey }`)
+   * to get the idempotent replay rather than a duplicate.
+   *
+   * @param params - `{ type, recipient: { username }, quantity | months, payment_currency?, callback_url? }`
+   * @param opts - optional caller-stable `idempotencyKey` (recommended) and `signal`
+   * @returns the {@link CreateOrderResult} — `payment` instruction + `expires_at`; `replayed` is `true` on a 200 idempotent replay
+   * @throws `MyStarsValidationError` if inputs are invalid
+   * @throws `RecipientIneligibleError` (422) if the recipient cannot receive the item (no order created)
+   * @throws `IdempotencyConflictError` (409) if the same key is reused with a different body
+   * @throws `MyStarsApiError` on any other API failure (carries the `idempotencyKey` for safe retry)
+   * @example
+   * ```ts
+   * const order = await client.createOrder(
+   *   { type: "stars", recipient: { username: "durov" }, quantity: 100 },
+   *   { idempotencyKey: `order-${myOrderId}` },
+   * );
+   * // pay order.payment.amount → order.payment.pay_to_address, comment = order.payment.memo
+   * ```
+   */
+  async createOrder(params, opts = {}) {
+    assertOrderType(params.type);
+    const body = {
+      type: params.type,
+      recipient: { username: canonicalUsername(params.recipient.username) }
+    };
+    if (params.type === "stars") {
+      assertStarsQuantity(params.quantity);
+      body.quantity = params.quantity;
+    } else {
+      assertPremiumMonths(params.months);
+      body.months = params.months;
+    }
+    if (params.payment_currency !== void 0) body.payment_currency = params.payment_currency;
+    if (params.callback_url !== void 0) body.callback_url = params.callback_url;
+    const idempotencyKey = opts.idempotencyKey ?? this.idempotencyKeyFactory();
+    try {
+      const { data, status } = await this.transport.request({
+        method: "POST",
+        path: "/orders",
+        body,
+        idempotencyKey,
+        signal: opts.signal
+      });
+      return { ...data, replayed: status === 200 };
+    } catch (err) {
+      if (err instanceof MyStarsApiError && err.idempotencyKey === void 0) {
+        err.idempotencyKey = idempotencyKey;
+      }
+      throw err;
+    }
+  }
+  /**
+   * `GET /v1/orders/:id` — fetch one order (tenant-scoped). Polling an
+   * `awaiting_payment` order also nudges the server's on-demand payment detection.
+   *
+   * @param orderId - the order UUID
+   * @param opts - optional `signal` to abort the request
+   * @returns the {@link Order}
+   * @throws `NotFoundError` (404) if no such order exists for this tenant
+   * @throws `MyStarsApiError` on any other API failure
+   */
+  async getOrder(orderId, opts = {}) {
+    const { data } = await this.transport.request({
+      method: "GET",
+      path: `/orders/${encodeURIComponent(orderId)}`,
+      signal: opts.signal
+    });
+    return data;
+  }
+  /**
+   * `POST /v1/orders/:id/cancel` — cancel an `awaiting_payment` order.
+   *
+   * @param orderId - the order UUID
+   * @param opts - optional `signal` to abort the request
+   * @returns `{ order_id, status: "cancelled" }`
+   * @throws `OrderNotCancellableError` (409) if the order is no longer `awaiting_payment` (a retry after a lost success can also surface this even though the cancel committed — re-check with `getOrder`)
+   * @throws `MyStarsApiError` on any other API failure
+   */
+  async cancelOrder(orderId, opts = {}) {
+    const { data } = await this.transport.request({
+      method: "POST",
+      path: `/orders/${encodeURIComponent(orderId)}/cancel`,
+      // Safe to retry: the cancel is a guarded transition (no double-action). Note a
+      // retry after a lost success can surface OrderNotCancellableError (409) even
+      // though the cancel committed — re-check with getOrder() if you catch one.
+      idempotent: true,
+      signal: opts.signal
+    });
+    return data;
+  }
+  listOrdersPage(params, cursor, signal) {
+    return this.transport.request({
+      method: "GET",
+      path: "/orders",
+      query: { status: params.status, limit: params.limit, cursor },
+      signal
+    }).then((r) => r.data);
+  }
+  /**
+   * `GET /v1/orders` — an auto-paginating view: `for await (const order of client.listOrders())`.
+   * The pager owns the cursor; `params.cursor` (if given) is the starting page.
+   *
+   * @param params - optional `status` filter, `limit` (1-100), and a starting `cursor`
+   * @param opts - optional `signal` to abort the underlying page fetches
+   * @returns an {@link OrdersPager} (async-iterable; `.pages()` / `.page()` / `.all()`)
+   * @example
+   * ```ts
+   * for await (const order of client.listOrders({ status: "delivered" })) {
+   *   console.log(order.order_id);
+   * }
+   * ```
+   */
+  listOrders(params = {}, opts = {}) {
+    return new OrdersPager((cursor) => this.listOrdersPage(params, cursor, opts.signal), params.cursor);
+  }
+  /**
+   * Poll `GET /v1/orders/:id` until the order is terminal (or the deadline).
+   *
+   * @param orderId - the order UUID
+   * @param options - the {@link WaitForOrderOptions} (intervals, deadline, `until`, `onUpdate`, `signal`)
+   * @returns the final {@link Order} once terminal
+   * @throws `OrderWaitTimeoutError` if `maxWaitMs` elapses first (carries the last snapshot)
+   * @throws `MyStarsApiError` if a poll fails non-transiently
+   * @example
+   * ```ts
+   * const final = await client.waitForOrder(order.order_id, { onUpdate: (o) => console.log(o.status) });
+   * ```
+   */
+  waitForOrder(orderId, options = {}) {
+    return waitForOrder(orderId, options, {
+      getOrder: (id, o) => this.getOrder(id, o),
+      sleep: this.sleep,
+      now: this.now,
+      random: this.random
+    });
+  }
+  /**
+   * Diff the server's orders against your local store to catch webhook-missed terminal transitions.
+   *
+   * @param options - the {@link ReconcileOptions}; `isKnown` is required, `since` bounds the scan
+   * @returns the missed terminal {@link Order}s, newest-first
+   * @throws `MyStarsApiError` if a page fetch fails
+   */
+  reconcile(options) {
+    return reconcile(this, options);
+  }
+};
+
+// src/webhook/verify.ts
+async function getSubtle() {
+  const c = globalThis.crypto;
+  if (c?.subtle) return c.subtle;
+  try {
+    const nodeCrypto = await import('crypto');
+    if (nodeCrypto.webcrypto?.subtle) return nodeCrypto.webcrypto.subtle;
+  } catch {
+  }
+  throw new Error("Web Crypto (globalThis.crypto.subtle) is unavailable in this runtime");
+}
+async function hmacSha256Hex(secret, body) {
+  const subtle = await getSubtle();
+  const enc = new TextEncoder();
+  const data = typeof body === "string" ? enc.encode(body) : new Uint8Array(body);
+  const key = await subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const sig = await subtle.sign("HMAC", key, data);
+  const out = new Uint8Array(sig);
+  let hex = "";
+  for (let i = 0; i < out.length; i++) hex += out[i].toString(16).padStart(2, "0");
+  return hex;
+}
+function timingSafeHexEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+async function verifyWebhookSignature(rawBody, signatureHeader, secret) {
+  if (!signatureHeader) return false;
+  const expected = await hmacSha256Hex(secret, rawBody);
+  let matched = false;
+  for (const part of signatureHeader.split(",")) {
+    if (timingSafeHexEqual(expected, part.trim())) matched = true;
+  }
+  return matched;
+}
+async function constructEvent(rawBody, signatureHeader, secret) {
+  const ok = await verifyWebhookSignature(rawBody, signatureHeader, secret);
+  if (!ok) throw new WebhookSignatureError("webhook signature verification failed");
+  const text = typeof rawBody === "string" ? rawBody : new TextDecoder().decode(rawBody);
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new WebhookSignatureError("webhook body is not valid JSON");
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new WebhookSignatureError("webhook body is not a JSON object");
+  }
+  const obj = parsed;
+  if (typeof obj.order_id !== "string") throw new WebhookSignatureError("webhook body is missing order_id");
+  if (typeof obj.status !== "string") throw new WebhookSignatureError("webhook body is missing status");
+  return parsed;
+}
+
+// src/webhook/middleware.ts
+function headerValue(value) {
+  if (Array.isArray(value)) return value[0];
+  return value;
+}
+function rawBodyString(body) {
+  if (typeof body === "string") return body;
+  if (body instanceof Uint8Array) return new TextDecoder().decode(body);
+  return void 0;
+}
+function expressWebhook(opts) {
+  return async (req, res) => {
+    const raw = rawBodyString(req.rawBody) ?? rawBodyString(req.body);
+    if (raw === void 0) {
+      res.status(400).send("raw body required (mount express.raw on this route)");
+      return;
+    }
+    const sig = headerValue(req.headers["x-faas-signature"]);
+    try {
+      const secret = typeof opts.secret === "function" ? await opts.secret(req) : opts.secret;
+      const event = await constructEvent(raw, sig, secret);
+      await opts.onEvent(event, { rawBody: raw, req });
+      res.status(200).send("ok");
+    } catch (err) {
+      const status = err instanceof WebhookSignatureError ? 400 : 500;
+      res.status(status).send(status === 400 ? "invalid signature" : "handler error");
+      opts.onError?.(err, req);
+    }
+  };
+}
+function fastifyWebhook(opts) {
+  return async (req, reply) => {
+    const raw = rawBodyString(req.rawBody) ?? rawBodyString(req.body);
+    if (raw === void 0) {
+      reply.code(400).send("raw body required (use a buffer content-type parser)");
+      return;
+    }
+    const sig = headerValue(req.headers["x-faas-signature"]);
+    try {
+      const secret = typeof opts.secret === "function" ? await opts.secret(req) : opts.secret;
+      const event = await constructEvent(raw, sig, secret);
+      await opts.onEvent(event, { rawBody: raw, req });
+      reply.code(200).send("ok");
+    } catch (err) {
+      const status = err instanceof WebhookSignatureError ? 400 : 500;
+      reply.code(status).send(status === 400 ? "invalid signature" : "handler error");
+      opts.onError?.(err, req);
+    }
+  };
+}
+
+// src/pricing/markup.ts
+function ceilUsdToCents(usd) {
+  const micro = Math.round(usd * 1e6);
+  return Math.ceil(micro / 1e4) / 100;
+}
+function ceilTonTo4dp(ton) {
+  const nano = Math.round(ton * 1e9);
+  return Math.ceil(nano / 1e5) / 1e4;
+}
+function num(value, label) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) throw new MyStarsValidationError(`${label} must be a finite decimal, got "${value}"`);
+  return n;
+}
+function fmtUsd(n) {
+  return n.toFixed(2);
+}
+function fmtTon(n) {
+  let s = n.toFixed(4);
+  if (s.includes(".")) s = s.replace(/0+$/, "").replace(/\.$/, "");
+  return s;
+}
+function applyRetailMarkup(input, config) {
+  const marginPct = config.marginPct;
+  if (!Number.isFinite(marginPct) || marginPct < 0) {
+    throw new MyStarsValidationError(`marginPct must be a non-negative number, got ${marginPct}`);
+  }
+  const passThrough = config.passThroughProcessingFee ?? true;
+  const amount = num(input.amount, "amount");
+  const factor = 1 + marginPct / 100;
+  if (input.currency === "usdt_ton") {
+    if (!input.fee) {
+      throw new MyStarsValidationError(
+        "usdt_ton amount has no fee breakdown; re-quote via GET /v1/pricing before applying markup"
+      );
+    }
+    const goods = num(input.fee.subtotal, "fee.subtotal");
+    const ourFee = num(input.fee.processing_fee, "fee.processing_fee");
+    const retailGoods2 = ceilUsdToCents(goods * factor);
+    const customerFee = passThrough ? ceilUsdToCents(ourFee) : 0;
+    const markup2 = retailGoods2 - goods;
+    const total = retailGoods2 + customerFee;
+    const profit = total - amount;
+    return {
+      currency: "usdt_ton",
+      wholesaleAmount: input.amount,
+      marginPct,
+      goods: fmtUsd(goods),
+      markup: fmtUsd(markup2),
+      subtotal: fmtUsd(retailGoods2),
+      processingFee: fmtUsd(customerFee),
+      total: fmtUsd(total),
+      profit: fmtUsd(profit),
+      lineItems: [
+        { label: "Goods", amount: fmtUsd(goods) },
+        { label: `Retail margin (${marginPct}%)`, amount: fmtUsd(markup2) },
+        { label: "Processing fee", amount: fmtUsd(customerFee) }
+      ]
+    };
+  }
+  const retailGoods = ceilTonTo4dp(amount * factor);
+  const markup = retailGoods - amount;
+  return {
+    currency: "ton",
+    wholesaleAmount: input.amount,
+    marginPct,
+    goods: fmtTon(amount),
+    markup: fmtTon(markup),
+    subtotal: fmtTon(retailGoods),
+    processingFee: "0",
+    total: fmtTon(retailGoods),
+    profit: fmtTon(markup),
+    lineItems: [
+      { label: "Goods", amount: fmtTon(amount) },
+      { label: `Retail margin (${marginPct}%)`, amount: fmtTon(markup) }
+    ]
+  };
+}
+
+// src/payment/util.ts
+function bytesToBase64(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  if (typeof btoa === "function") return btoa(binary);
+  if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
+  throw new Error("no base64 encoder available in this runtime");
+}
+function base64ToBytes(b64) {
+  if (typeof atob === "function") {
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+    return out;
+  }
+  if (typeof Buffer !== "undefined") return new Uint8Array(Buffer.from(b64, "base64"));
+  throw new Error("no base64 decoder available in this runtime");
+}
+function crc32c(data) {
+  const POLY = 2197175160;
+  let crc = 4294967295;
+  for (let i = 0; i < data.length; i++) {
+    crc ^= data[i];
+    for (let j = 0; j < 8; j++) {
+      crc = crc & 1 ? crc >>> 1 ^ POLY : crc >>> 1;
+    }
+  }
+  return (crc ^ 4294967295) >>> 0;
+}
+function crc16xmodem(data) {
+  let crc = 0;
+  for (let i = 0; i < data.length; i++) {
+    crc ^= data[i] << 8;
+    for (let j = 0; j < 8; j++) {
+      crc = crc & 32768 ? crc << 1 ^ 4129 : crc << 1;
+      crc &= 65535;
+    }
+  }
+  return crc;
+}
+
+// src/payment/cell.ts
+var MAX_COMMENT_BYTES = 123;
+function buildCommentPayload(comment) {
+  const textBytes = new TextEncoder().encode(comment);
+  if (32 + textBytes.length * 8 > 1023) {
+    throw new MyStarsValidationError(
+      `comment is ${textBytes.length} UTF-8 bytes; max ${MAX_COMMENT_BYTES} fit in a single-cell op-0 payload`
+    );
+  }
+  const totalBits = 32 + textBytes.length * 8;
+  const dataBytes = Math.ceil(totalBits / 8);
+  const data = new Uint8Array(dataBytes);
+  data.set(textBytes, 4);
+  const d1 = 0;
+  const d2Actual = totalBits % 8 === 0 ? totalBits / 8 * 2 : Math.floor(totalBits / 8) * 2 + 1;
+  const cellData = new Uint8Array(Math.ceil(totalBits / 8));
+  cellData.set(data.subarray(0, cellData.length));
+  if (totalBits % 8 !== 0) {
+    const shift = 8 - totalBits % 8;
+    cellData[cellData.length - 1] |= 1 << shift - 1;
+  }
+  const cellPayload = new Uint8Array(2 + cellData.length);
+  cellPayload[0] = d1;
+  cellPayload[1] = d2Actual;
+  cellPayload.set(cellData, 2);
+  const cellsSize = cellPayload.length;
+  const offsetBytes = 1;
+  const headerSize = 4 + 1 + 1 + 1 + 1 + 1 + offsetBytes + 1;
+  const boc = new Uint8Array(headerSize + cellsSize + 4);
+  let pos = 0;
+  boc[pos++] = 181;
+  boc[pos++] = 238;
+  boc[pos++] = 156;
+  boc[pos++] = 114;
+  boc[pos++] = 1 << 6 | offsetBytes;
+  boc[pos++] = offsetBytes;
+  boc[pos++] = 1;
+  boc[pos++] = 1;
+  boc[pos++] = 0;
+  boc[pos++] = cellsSize;
+  boc[pos++] = 0;
+  boc.set(cellPayload, pos);
+  pos += cellsSize;
+  const crc = crc32c(boc.subarray(0, pos));
+  boc[pos++] = crc & 255;
+  boc[pos++] = crc >> 8 & 255;
+  boc[pos++] = crc >> 16 & 255;
+  boc[pos++] = crc >> 24 & 255;
+  return bytesToBase64(boc);
+}
+
+// src/payment/jetton.ts
+var MAX_MEMO_BYTES = 123;
+var FORWARD_TON_AMOUNT_NANO = BigInt(0);
+var JETTON_TRANSFER_OP = 260734629;
+var BitBuilder = class {
+  fullBytes = [];
+  currentByte = 0;
+  bitPos = 0;
+  storeUint(value, bits) {
+    const v = BigInt(value);
+    for (let i = bits - 1; i >= 0; i--) {
+      const bit = Number(v >> BigInt(i) & BigInt(1));
+      this.currentByte = this.currentByte << 1 | bit;
+      this.bitPos++;
+      if (this.bitPos === 8) {
+        this.fullBytes.push(this.currentByte);
+        this.currentByte = 0;
+        this.bitPos = 0;
+      }
+    }
+    return this;
+  }
+  storeBit(bit) {
+    return this.storeUint(bit, 1);
+  }
+  /** Store a Coins value (VarUInteger 16): 4-bit byte-length prefix + big-endian bytes. Zero → 4 zero bits. */
+  storeCoins(amount) {
+    if (amount === BigInt(0)) return this.storeUint(0, 4);
+    const hex = amount.toString(16);
+    const byteLen = Math.ceil(hex.length / 2);
+    this.storeUint(byteLen, 4);
+    const padded = hex.padStart(byteLen * 2, "0");
+    for (let i = 0; i < byteLen; i++) {
+      this.storeUint(parseInt(padded.slice(i * 2, i * 2 + 2), 16), 8);
+    }
+    return this;
+  }
+  /** Store MsgAddress std (addr_std$10). Accepts friendly (base64url) or raw (`wc:hex`) forms. */
+  storeAddress(address) {
+    const { workchain, hash } = parseTonAddress(address);
+    this.storeUint(2, 2);
+    this.storeBit(0);
+    this.storeUint(workchain < 0 ? 256 + workchain : workchain, 8);
+    for (const byte of hash) this.storeUint(byte, 8);
+    return this;
+  }
+  /** Store a UTF-8 string as raw bytes (no length prefix). */
+  storeStringTail(text) {
+    const bytes = new TextEncoder().encode(text);
+    for (const byte of bytes) this.storeUint(byte, 8);
+    return this;
+  }
+  get totalBits() {
+    return this.fullBytes.length * 8 + this.bitPos;
+  }
+  finalize() {
+    const bits = this.totalBits;
+    const byteLen = Math.ceil(bits / 8);
+    const result = new Uint8Array(byteLen);
+    for (let i = 0; i < this.fullBytes.length; i++) result[i] = this.fullBytes[i];
+    if (this.bitPos > 0) result[this.fullBytes.length] = this.currentByte << 8 - this.bitPos;
+    return { data: result, bits };
+  }
+};
+function parseTonAddress(address) {
+  if (address.includes(":")) {
+    const colonIdx = address.indexOf(":");
+    const wc = address.slice(0, colonIdx);
+    const hashHex = address.slice(colonIdx + 1);
+    if (!/^-?\d+$/.test(wc)) throw new Error(`Invalid TON address: bad workchain "${wc}"`);
+    const workchain2 = Number(wc);
+    if (workchain2 !== 0 && workchain2 !== -1) {
+      throw new Error(`Invalid TON address: workchain must be 0 or -1, got ${workchain2}`);
+    }
+    if (!hashHex || hashHex.length !== 64 || !/^[0-9a-fA-F]{64}$/.test(hashHex)) {
+      throw new Error("Invalid TON address: hash must be 64 hex characters");
+    }
+    const hash2 = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) hash2[i] = parseInt(hashHex.slice(i * 2, i * 2 + 2), 16);
+    return { workchain: workchain2, hash: hash2 };
+  }
+  const standard = address.replace(/-/g, "+").replace(/_/g, "/");
+  let bytes;
+  try {
+    bytes = base64ToBytes(standard);
+  } catch {
+    throw new Error("Invalid TON address: not valid base64");
+  }
+  if (bytes.length !== 36) throw new Error(`Invalid TON address: expected 36 bytes, got ${bytes.length}`);
+  const payload = bytes.subarray(0, 34);
+  const expectedCrc = bytes[34] << 8 | bytes[35];
+  const actualCrc = crc16xmodem(payload);
+  if (expectedCrc !== actualCrc) {
+    throw new Error(
+      `Invalid TON address: checksum mismatch (expected ${expectedCrc.toString(16)}, got ${actualCrc.toString(16)})`
+    );
+  }
+  const workchain = bytes[1] > 127 ? bytes[1] - 256 : bytes[1];
+  const hash = bytes.slice(2, 34);
+  return { workchain, hash };
+}
+function serializeCell(data, bits, refIndices) {
+  const dataLen = Math.ceil(bits / 8);
+  const d1 = refIndices.length;
+  const d2 = bits % 8 === 0 ? bits / 8 * 2 : Math.floor(bits / 8) * 2 + 1;
+  const cellData = new Uint8Array(dataLen);
+  cellData.set(data.subarray(0, dataLen));
+  if (bits % 8 !== 0) {
+    const remaining = bits % 8;
+    cellData[dataLen - 1] |= 1 << 8 - remaining - 1;
+  }
+  const result = new Uint8Array(2 + dataLen + refIndices.length);
+  result[0] = d1;
+  result[1] = d2;
+  result.set(cellData, 2);
+  for (let i = 0; i < refIndices.length; i++) result[2 + dataLen + i] = refIndices[i];
+  return result;
+}
+function serializeBoC(cells) {
+  const cellCount = cells.length;
+  const totalCellsSize = cells.reduce((sum, c) => sum + c.length, 0);
+  const offsetBytes = totalCellsSize < 256 ? 1 : 2;
+  const refByteSize = 1;
+  const headerSize = 4 + 1 + 1 + refByteSize * 3 + offsetBytes + refByteSize;
+  const boc = new Uint8Array(headerSize + totalCellsSize + 4);
+  let pos = 0;
+  boc[pos++] = 181;
+  boc[pos++] = 238;
+  boc[pos++] = 156;
+  boc[pos++] = 114;
+  boc[pos++] = 1 << 6 | refByteSize;
+  boc[pos++] = offsetBytes;
+  boc[pos++] = cellCount;
+  boc[pos++] = 1;
+  boc[pos++] = 0;
+  if (offsetBytes === 2) boc[pos++] = totalCellsSize >> 8 & 255;
+  boc[pos++] = totalCellsSize & 255;
+  boc[pos++] = 0;
+  for (const cell of cells) {
+    boc.set(cell, pos);
+    pos += cell.length;
+  }
+  const crc = crc32c(boc.subarray(0, pos));
+  boc[pos++] = crc & 255;
+  boc[pos++] = crc >> 8 & 255;
+  boc[pos++] = crc >> 16 & 255;
+  boc[pos++] = crc >> 24 & 255;
+  return bytesToBase64(boc);
+}
+function buildJettonTransferPayload(amountMicro, destination, sender, memo) {
+  const memoBytes = new TextEncoder().encode(memo).length;
+  if (32 + memoBytes * 8 > 1023) {
+    throw new MyStarsValidationError(
+      `memo is ${memoBytes} UTF-8 bytes; max ${MAX_MEMO_BYTES} fit in a single-cell op-0 forward payload`
+    );
+  }
+  const refBuilder = new BitBuilder();
+  refBuilder.storeUint(0, 32).storeStringTail(memo);
+  const refCell = refBuilder.finalize();
+  const serializedRef = serializeCell(refCell.data, refCell.bits, []);
+  const bodyBuilder = new BitBuilder();
+  bodyBuilder.storeUint(JETTON_TRANSFER_OP, 32).storeUint(0, 64).storeCoins(BigInt(amountMicro)).storeAddress(destination).storeAddress(sender).storeBit(0).storeCoins(FORWARD_TON_AMOUNT_NANO).storeBit(1);
+  const bodyCell = bodyBuilder.finalize();
+  const serializedBody = serializeCell(bodyCell.data, bodyCell.bits, [1]);
+  return serializeBoC([serializedBody, serializedRef]);
+}
+
+// src/payment/invoice.ts
+var JETTON_TRANSFER_GAS_NANO = "50000000";
+var DECIMAL_RE = /^\d+(\.\d+)?$/;
+function decimalToUnits(amount, decimals) {
+  if (amount.trimStart().startsWith("-")) {
+    throw new MyStarsValidationError(`amount must not be negative, got "${amount}"`);
+  }
+  if (!DECIMAL_RE.test(amount)) throw new MyStarsValidationError(`invalid decimal amount "${amount}"`);
+  const [intPart, fracPart = ""] = amount.split(".");
+  const scaledFrac = fracPart.padEnd(decimals + 1, "0");
+  const keep = scaledFrac.slice(0, decimals);
+  const roundDigit = scaledFrac[decimals];
+  let units = BigInt((intPart || "0") + keep);
+  if (roundDigit !== void 0 && Number(roundDigit) >= 5) units += 1n;
+  return units;
+}
+function toNano(amount) {
+  return decimalToUnits(amount, 9);
+}
+function toMicro(amount) {
+  return decimalToUnits(amount, 6);
+}
+function requireAddress(p) {
+  if (!p.pay_to_address) throw new MyStarsValidationError("payment.pay_to_address is missing");
+  return p.pay_to_address;
+}
+function requireMemo(p) {
+  if (!p.memo) throw new MyStarsValidationError("payment.memo is missing");
+  return p.memo;
+}
+function requirePositiveUnits(p) {
+  const units = p.currency === "ton" ? toNano(p.amount) : toMicro(p.amount);
+  if (units <= 0n) {
+    throw new MyStarsValidationError(`payment amount must be positive, got "${p.amount}"`);
+  }
+  return units;
+}
+function buildTonConnectMessages(payment, opts = {}) {
+  const payTo = requireAddress(payment);
+  const memo = requireMemo(payment);
+  requirePositiveUnits(payment);
+  if (payment.currency === "ton") {
+    return [{ address: payTo, amount: toNano(payment.amount).toString(), payload: buildCommentPayload(memo) }];
+  }
+  if (!opts.senderAddress || !opts.jettonWalletAddress) {
+    throw new MyStarsValidationError(
+      "a USDT TON Connect message needs senderAddress + jettonWalletAddress (the payer's own USDT jetton wallet)"
+    );
+  }
+  const payload = buildJettonTransferPayload(toMicro(payment.amount), payTo, opts.senderAddress, memo);
+  return [{ address: opts.jettonWalletAddress, amount: JETTON_TRANSFER_GAS_NANO, payload }];
+}
+function buildTonDeeplink(payment) {
+  if (payment.currency !== "ton") {
+    throw new MyStarsValidationError("a ton:// deeplink is only valid for `ton` payments (USDT needs a jetton transfer)");
+  }
+  const payTo = requireAddress(payment);
+  const memo = requireMemo(payment);
+  requirePositiveUnits(payment);
+  const nano = toNano(payment.amount).toString();
+  return `ton://transfer/${payTo}?amount=${nano}&text=${encodeURIComponent(memo)}`;
+}
+function buildPaymentRequest(payment, opts = {}) {
+  const payTo = requireAddress(payment);
+  const memo = requireMemo(payment);
+  requirePositiveUnits(payment);
+  if (payment.currency === "ton") {
+    const nano = toNano(payment.amount).toString();
+    const deeplink = `ton://transfer/${payTo}?amount=${nano}&text=${encodeURIComponent(memo)}`;
+    return {
+      currency: "ton",
+      payToAddress: payTo,
+      memo,
+      amountUnits: "ton",
+      amountSmallestUnit: nano,
+      tonDeeplink: deeplink,
+      tonkeeperLink: `https://app.tonkeeper.com/transfer/${payTo}?amount=${nano}&text=${encodeURIComponent(memo)}`,
+      qrPayload: deeplink,
+      tonConnect: [{ address: payTo, amount: nano, payload: buildCommentPayload(memo) }]
+    };
+  }
+  const micro = toMicro(payment.amount).toString();
+  const base = {
+    currency: "usdt_ton",
+    payToAddress: payTo,
+    memo,
+    amountUnits: "usdt",
+    amountSmallestUnit: micro,
+    tonConnect: []
+  };
+  if (opts.senderAddress && opts.jettonWalletAddress) {
+    base.tonConnect = buildTonConnectMessages(payment, opts);
+  } else {
+    base.note = "USDT: pass senderAddress + jettonWalletAddress (the payer's own USDT jetton wallet) to build a signable TON Connect message.";
+  }
+  return base;
+}
+
+export { BadRequestError, CANCELLABLE_STATUSES, CONTRACT_VERSION, ConflictError, FORWARD_TON_AMOUNT_NANO, ForbiddenError, INITIAL_ORDER_STATUS, IdempotencyConflictError, InternalServerError, JETTON_TRANSFER_GAS_NANO, JETTON_TRANSFER_OP, MyStarsApiError, MyStarsClient, MyStarsError, MyStarsValidationError, NetworkError, NotFoundError, OrderNotCancellableError, OrderWaitTimeoutError, OrdersPager, PREMIUM_MONTHS, PRODUCTION_BASE_URL, RateLimitError, RecipientIneligibleError, SDK_VERSION, STARS_MAX_QUANTITY, STARS_MIN_QUANTITY, ServiceUnavailableError, TERMINAL_STATUSES, TimeoutError, UnauthorizedError, WEBHOOK_TERMINAL, WebhookSignatureError, applyRetailMarkup, buildCommentPayload, buildJettonTransferPayload, buildPaymentRequest, buildTonConnectMessages, buildTonDeeplink, canonicalUsername, ceilTonTo4dp, ceilUsdToCents, constructEvent, decimalToUnits, defaultShouldRetry, errorFromResponse, expressWebhook, fastifyWebhook, isTerminal, parseRetryAfterMs, parseTonAddress, reconcile, toMicro, toNano, verifyWebhookSignature };