@mystars-tg/faas-cli 0.1.2

package/LICENSE

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

package/README.md

@@ -0,0 +1,44 @@
+# @mystars-tg/faas-cli
+
+[![npm](https://img.shields.io/npm/v/@mystars-tg/faas-cli.svg)](https://www.npmjs.com/package/@mystars-tg/faas-cli) [![license](https://img.shields.io/npm/l/@mystars-tg/faas-cli.svg)](LICENSE)
+
+Command-line tool for the MyStars FaaS API — quoting, recipient checks, order management, payment
+links, and webhook verification. Great for onboarding, support, and quick smoke tests.
+
+📖 API reference: **[mystars.tg/docs](https://mystars.tg/docs)**.
+
+## Use it
+
+```bash
+# No install needed:
+npx @mystars-tg/faas-cli --help
+
+# Or install globally:
+npm install -g @mystars-tg/faas-cli
+```
+
+Authenticate with `--api-key <key>` or `MYSTARS_API_KEY`. Every command prints JSON to stdout.
+
+```bash
+export MYSTARS_API_KEY=faas_...
+
+mystars-faas pricing --type stars --quantity 100 --currency ton
+mystars-faas products
+mystars-faas recipient-check durov --type stars
+mystars-faas orders create --type stars --recipient durov --quantity 100 --pay   # prints a payable deeplink/QR/TON Connect
+mystars-faas orders get <order-id>
+mystars-faas orders ls --status delivered --limit 50
+mystars-faas orders cancel <order-id>
+mystars-faas watch <order-id>                                                     # poll until terminal
+
+# webhook-verify: PREFER the env var — a secret on the command line leaks into `ps` + shell history.
+export MYSTARS_WEBHOOK_SECRET=...
+mystars-faas webhook-verify --body '<raw-json>' --signature <X-Faas-Signature>
+```
+
+`webhook-verify` runs entirely offline — handy for debugging a signature locally. The webhook secret
+comes from `MYSTARS_WEBHOOK_SECRET` (preferred) or `--secret <secret>`; the env var **wins** when both
+are set, because a secret passed on the command line is visible in the process list (`ps`) and your
+shell history. The CLI never holds keys or moves funds; `orders create --pay` only **prints** a payment
+request you can pay from your own wallet (see `@mystars-tg/faas-wallet` for programmatic signing +
+broadcasting).

package/dist/bin.cjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/bin.ts
+var import_commander = require("commander");
+var import_faas_sdk2 = require("@mystars-tg/faas-sdk");
+
+// src/commands.ts
+var import_faas_sdk = require("@mystars-tg/faas-sdk");
+function print(io2, value) {
+  io2.out(JSON.stringify(value, null, 2));
+}
+async function cmdPricing(client, opts, io2) {
+  const quote = opts.type === "stars" ? await client.getPricing({ type: "stars", quantity: opts.quantity, payment_currency: opts.currency }) : await client.getPricing({ type: "premium", months: opts.months, payment_currency: opts.currency });
+  print(io2, quote);
+}
+async function cmdProducts(client, io2) {
+  print(io2, await client.listProducts());
+}
+async function cmdCurrencies(client, io2) {
+  print(io2, await client.listCurrencies());
+}
+async function cmdRecipientCheck(client, opts, io2) {
+  const res = opts.type === "stars" ? await client.checkRecipient({ type: "stars", recipient: { username: opts.username } }) : await client.checkRecipient({ type: "premium", recipient: { username: opts.username }, months: opts.months });
+  print(io2, res);
+}
+async function cmdOrdersCreate(client, opts, io2) {
+  const order = opts.type === "stars" ? await client.createOrder({ type: "stars", recipient: { username: opts.recipient }, quantity: opts.quantity, payment_currency: opts.currency, callback_url: opts.callback }) : await client.createOrder({ type: "premium", recipient: { username: opts.recipient }, months: opts.months, payment_currency: opts.currency, callback_url: opts.callback });
+  if (opts.pay) {
+    print(io2, { order, payment_request: (0, import_faas_sdk.buildPaymentRequest)(order.payment) });
+  } else {
+    print(io2, order);
+  }
+}
+async function cmdOrdersGet(client, id, io2) {
+  print(io2, await client.getOrder(id));
+}
+async function cmdOrdersList(client, opts, io2) {
+  const page = await client.listOrders(opts).page();
+  print(io2, page);
+}
+async function cmdOrdersCancel(client, id, io2) {
+  print(io2, await client.cancelOrder(id));
+}
+async function cmdWatch(client, id, io2) {
+  const final = await client.waitForOrder(id, {
+    onUpdate: (o) => io2.err(`status: ${o.status}`)
+  });
+  print(io2, final);
+}
+function resolveWebhookSecret(optSecret, env = process.env) {
+  const secret = env.MYSTARS_WEBHOOK_SECRET || optSecret;
+  if (!secret) {
+    throw new Error("a webhook secret is required (set MYSTARS_WEBHOOK_SECRET, or pass --secret <secret>)");
+  }
+  return secret;
+}
+async function cmdWebhookVerify(opts, io2) {
+  const valid = await (0, import_faas_sdk.verifyWebhookSignature)(opts.body, opts.signature, opts.secret);
+  print(io2, { valid });
+}
+
+// src/bin.ts
+var program = new import_commander.Command();
+var io = { out: (s) => console.log(s), err: (s) => console.error(s) };
+program.name("mystars-faas").description("CLI for the MyStars FaaS API (Telegram Stars & Premium for any @username).").version("0.1.2").option("--api-key <key>", "tenant API key (or set MYSTARS_API_KEY)");
+function makeClient() {
+  const opts = program.opts();
+  const apiKey = opts.apiKey ?? process.env.MYSTARS_API_KEY;
+  if (!apiKey) {
+    io.err("error: an API key is required (--api-key <key> or MYSTARS_API_KEY)");
+    process.exit(1);
+  }
+  return import_faas_sdk2.MyStarsClient.production(apiKey);
+}
+function fail(msg) {
+  io.err(`error: ${msg}`);
+  process.exit(1);
+}
+var num = (v, name) => {
+  if (v === void 0) return void 0;
+  const n = Number(v);
+  if (!Number.isFinite(n)) fail(`--${name} must be a number, got "${v}"`);
+  return n;
+};
+function asType(t) {
+  if (t !== "stars" && t !== "premium") fail(`--type must be "stars" or "premium", got "${t}"`);
+  return t;
+}
+program.command("pricing").description("quote a price").requiredOption("--type <type>", "stars | premium").option("--quantity <n>", "stars quantity").option("--months <n>", "premium months (3|6|12)").option("--currency <c>", "ton | usdt_ton").action(
+  (o) => cmdPricing(makeClient(), { type: asType(o.type), quantity: num(o.quantity, "quantity"), months: num(o.months, "months"), currency: o.currency }, io)
+);
+program.command("products").description("list the product catalog").action(() => cmdProducts(makeClient(), io));
+program.command("currencies").description("list payment currencies").action(() => cmdCurrencies(makeClient(), io));
+program.command("recipient-check").description("resolve a @username and check eligibility").argument("<username>").requiredOption("--type <type>", "stars | premium").option("--months <n>", "premium months").action((username, o) => cmdRecipientCheck(makeClient(), { type: asType(o.type), username, months: num(o.months, "months") }, io));
+var orders = program.command("orders").description("manage orders");
+orders.command("create").requiredOption("--type <type>", "stars | premium").requiredOption("--recipient <username>").option("--quantity <n>").option("--months <n>").option("--currency <c>", "ton | usdt_ton").option("--callback <url>", "webhook callback_url").option("--pay", "also print a payable request (deeplink / QR / TON Connect)").action(
+  (o) => cmdOrdersCreate(
+    makeClient(),
+    { type: asType(o.type), recipient: o.recipient, quantity: num(o.quantity, "quantity"), months: num(o.months, "months"), currency: o.currency, callback: o.callback, pay: o.pay },
+    io
+  )
+);
+orders.command("get").argument("<id>").action((id) => cmdOrdersGet(makeClient(), id, io));
+orders.command("ls").option("--status <status>").option("--limit <n>").action((o) => cmdOrdersList(makeClient(), { status: o.status, limit: num(o.limit, "limit") }, io));
+orders.command("cancel").argument("<id>").action((id) => cmdOrdersCancel(makeClient(), id, io));
+program.command("watch").description("poll an order until it's terminal").argument("<id>").action((id) => cmdWatch(makeClient(), id, io));
+program.command("webhook-verify").description("verify an X-Faas-Signature over a raw body").option(
+  "--secret <secret>",
+  "tenant webhook secret (PREFER MYSTARS_WEBHOOK_SECRET \u2014 a secret on the command line leaks into `ps` and shell history)"
+).requiredOption("--body <json>").requiredOption("--signature <sig>").action(
+  (o) => cmdWebhookVerify({ secret: resolveWebhookSecret(o.secret), body: o.body, signature: o.signature }, io)
+);
+program.parseAsync(process.argv).catch((e) => {
+  io.err(e instanceof Error ? e.message : String(e));
+  process.exit(1);
+});

package/dist/bin.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import {
+  cmdCurrencies,
+  cmdOrdersCancel,
+  cmdOrdersCreate,
+  cmdOrdersGet,
+  cmdOrdersList,
+  cmdPricing,
+  cmdProducts,
+  cmdRecipientCheck,
+  cmdWatch,
+  cmdWebhookVerify,
+  resolveWebhookSecret
+} from "./chunk-LVDNP4X2.js";
+
+// src/bin.ts
+import { Command } from "commander";
+import { MyStarsClient } from "@mystars-tg/faas-sdk";
+var program = new Command();
+var io = { out: (s) => console.log(s), err: (s) => console.error(s) };
+program.name("mystars-faas").description("CLI for the MyStars FaaS API (Telegram Stars & Premium for any @username).").version("0.1.2").option("--api-key <key>", "tenant API key (or set MYSTARS_API_KEY)");
+function makeClient() {
+  const opts = program.opts();
+  const apiKey = opts.apiKey ?? process.env.MYSTARS_API_KEY;
+  if (!apiKey) {
+    io.err("error: an API key is required (--api-key <key> or MYSTARS_API_KEY)");
+    process.exit(1);
+  }
+  return MyStarsClient.production(apiKey);
+}
+function fail(msg) {
+  io.err(`error: ${msg}`);
+  process.exit(1);
+}
+var num = (v, name) => {
+  if (v === void 0) return void 0;
+  const n = Number(v);
+  if (!Number.isFinite(n)) fail(`--${name} must be a number, got "${v}"`);
+  return n;
+};
+function asType(t) {
+  if (t !== "stars" && t !== "premium") fail(`--type must be "stars" or "premium", got "${t}"`);
+  return t;
+}
+program.command("pricing").description("quote a price").requiredOption("--type <type>", "stars | premium").option("--quantity <n>", "stars quantity").option("--months <n>", "premium months (3|6|12)").option("--currency <c>", "ton | usdt_ton").action(
+  (o) => cmdPricing(makeClient(), { type: asType(o.type), quantity: num(o.quantity, "quantity"), months: num(o.months, "months"), currency: o.currency }, io)
+);
+program.command("products").description("list the product catalog").action(() => cmdProducts(makeClient(), io));
+program.command("currencies").description("list payment currencies").action(() => cmdCurrencies(makeClient(), io));
+program.command("recipient-check").description("resolve a @username and check eligibility").argument("<username>").requiredOption("--type <type>", "stars | premium").option("--months <n>", "premium months").action((username, o) => cmdRecipientCheck(makeClient(), { type: asType(o.type), username, months: num(o.months, "months") }, io));
+var orders = program.command("orders").description("manage orders");
+orders.command("create").requiredOption("--type <type>", "stars | premium").requiredOption("--recipient <username>").option("--quantity <n>").option("--months <n>").option("--currency <c>", "ton | usdt_ton").option("--callback <url>", "webhook callback_url").option("--pay", "also print a payable request (deeplink / QR / TON Connect)").action(
+  (o) => cmdOrdersCreate(
+    makeClient(),
+    { type: asType(o.type), recipient: o.recipient, quantity: num(o.quantity, "quantity"), months: num(o.months, "months"), currency: o.currency, callback: o.callback, pay: o.pay },
+    io
+  )
+);
+orders.command("get").argument("<id>").action((id) => cmdOrdersGet(makeClient(), id, io));
+orders.command("ls").option("--status <status>").option("--limit <n>").action((o) => cmdOrdersList(makeClient(), { status: o.status, limit: num(o.limit, "limit") }, io));
+orders.command("cancel").argument("<id>").action((id) => cmdOrdersCancel(makeClient(), id, io));
+program.command("watch").description("poll an order until it's terminal").argument("<id>").action((id) => cmdWatch(makeClient(), id, io));
+program.command("webhook-verify").description("verify an X-Faas-Signature over a raw body").option(
+  "--secret <secret>",
+  "tenant webhook secret (PREFER MYSTARS_WEBHOOK_SECRET \u2014 a secret on the command line leaks into `ps` and shell history)"
+).requiredOption("--body <json>").requiredOption("--signature <sig>").action(
+  (o) => cmdWebhookVerify({ secret: resolveWebhookSecret(o.secret), body: o.body, signature: o.signature }, io)
+);
+program.parseAsync(process.argv).catch((e) => {
+  io.err(e instanceof Error ? e.message : String(e));
+  process.exit(1);
+});

package/dist/chunk-LVDNP4X2.js

@@ -0,0 +1,71 @@
+// src/commands.ts
+import {
+  buildPaymentRequest,
+  verifyWebhookSignature
+} from "@mystars-tg/faas-sdk";
+function print(io, value) {
+  io.out(JSON.stringify(value, null, 2));
+}
+async function cmdPricing(client, opts, io) {
+  const quote = opts.type === "stars" ? await client.getPricing({ type: "stars", quantity: opts.quantity, payment_currency: opts.currency }) : await client.getPricing({ type: "premium", months: opts.months, payment_currency: opts.currency });
+  print(io, quote);
+}
+async function cmdProducts(client, io) {
+  print(io, await client.listProducts());
+}
+async function cmdCurrencies(client, io) {
+  print(io, await client.listCurrencies());
+}
+async function cmdRecipientCheck(client, opts, io) {
+  const res = opts.type === "stars" ? await client.checkRecipient({ type: "stars", recipient: { username: opts.username } }) : await client.checkRecipient({ type: "premium", recipient: { username: opts.username }, months: opts.months });
+  print(io, res);
+}
+async function cmdOrdersCreate(client, opts, io) {
+  const order = opts.type === "stars" ? await client.createOrder({ type: "stars", recipient: { username: opts.recipient }, quantity: opts.quantity, payment_currency: opts.currency, callback_url: opts.callback }) : await client.createOrder({ type: "premium", recipient: { username: opts.recipient }, months: opts.months, payment_currency: opts.currency, callback_url: opts.callback });
+  if (opts.pay) {
+    print(io, { order, payment_request: buildPaymentRequest(order.payment) });
+  } else {
+    print(io, order);
+  }
+}
+async function cmdOrdersGet(client, id, io) {
+  print(io, await client.getOrder(id));
+}
+async function cmdOrdersList(client, opts, io) {
+  const page = await client.listOrders(opts).page();
+  print(io, page);
+}
+async function cmdOrdersCancel(client, id, io) {
+  print(io, await client.cancelOrder(id));
+}
+async function cmdWatch(client, id, io) {
+  const final = await client.waitForOrder(id, {
+    onUpdate: (o) => io.err(`status: ${o.status}`)
+  });
+  print(io, final);
+}
+function resolveWebhookSecret(optSecret, env = process.env) {
+  const secret = env.MYSTARS_WEBHOOK_SECRET || optSecret;
+  if (!secret) {
+    throw new Error("a webhook secret is required (set MYSTARS_WEBHOOK_SECRET, or pass --secret <secret>)");
+  }
+  return secret;
+}
+async function cmdWebhookVerify(opts, io) {
+  const valid = await verifyWebhookSignature(opts.body, opts.signature, opts.secret);
+  print(io, { valid });
+}
+
+export {
+  cmdPricing,
+  cmdProducts,
+  cmdCurrencies,
+  cmdRecipientCheck,
+  cmdOrdersCreate,
+  cmdOrdersGet,
+  cmdOrdersList,
+  cmdOrdersCancel,
+  cmdWatch,
+  resolveWebhookSecret,
+  cmdWebhookVerify
+};

package/dist/index.cjs

@@ -0,0 +1,95 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  cmdCurrencies: () => cmdCurrencies,
+  cmdOrdersCancel: () => cmdOrdersCancel,
+  cmdOrdersCreate: () => cmdOrdersCreate,
+  cmdOrdersGet: () => cmdOrdersGet,
+  cmdOrdersList: () => cmdOrdersList,
+  cmdPricing: () => cmdPricing,
+  cmdProducts: () => cmdProducts,
+  cmdRecipientCheck: () => cmdRecipientCheck,
+  cmdWatch: () => cmdWatch,
+  cmdWebhookVerify: () => cmdWebhookVerify
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/commands.ts
+var import_faas_sdk = require("@mystars-tg/faas-sdk");
+function print(io, value) {
+  io.out(JSON.stringify(value, null, 2));
+}
+async function cmdPricing(client, opts, io) {
+  const quote = opts.type === "stars" ? await client.getPricing({ type: "stars", quantity: opts.quantity, payment_currency: opts.currency }) : await client.getPricing({ type: "premium", months: opts.months, payment_currency: opts.currency });
+  print(io, quote);
+}
+async function cmdProducts(client, io) {
+  print(io, await client.listProducts());
+}
+async function cmdCurrencies(client, io) {
+  print(io, await client.listCurrencies());
+}
+async function cmdRecipientCheck(client, opts, io) {
+  const res = opts.type === "stars" ? await client.checkRecipient({ type: "stars", recipient: { username: opts.username } }) : await client.checkRecipient({ type: "premium", recipient: { username: opts.username }, months: opts.months });
+  print(io, res);
+}
+async function cmdOrdersCreate(client, opts, io) {
+  const order = opts.type === "stars" ? await client.createOrder({ type: "stars", recipient: { username: opts.recipient }, quantity: opts.quantity, payment_currency: opts.currency, callback_url: opts.callback }) : await client.createOrder({ type: "premium", recipient: { username: opts.recipient }, months: opts.months, payment_currency: opts.currency, callback_url: opts.callback });
+  if (opts.pay) {
+    print(io, { order, payment_request: (0, import_faas_sdk.buildPaymentRequest)(order.payment) });
+  } else {
+    print(io, order);
+  }
+}
+async function cmdOrdersGet(client, id, io) {
+  print(io, await client.getOrder(id));
+}
+async function cmdOrdersList(client, opts, io) {
+  const page = await client.listOrders(opts).page();
+  print(io, page);
+}
+async function cmdOrdersCancel(client, id, io) {
+  print(io, await client.cancelOrder(id));
+}
+async function cmdWatch(client, id, io) {
+  const final = await client.waitForOrder(id, {
+    onUpdate: (o) => io.err(`status: ${o.status}`)
+  });
+  print(io, final);
+}
+async function cmdWebhookVerify(opts, io) {
+  const valid = await (0, import_faas_sdk.verifyWebhookSignature)(opts.body, opts.signature, opts.secret);
+  print(io, { valid });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  cmdCurrencies,
+  cmdOrdersCancel,
+  cmdOrdersCreate,
+  cmdOrdersGet,
+  cmdOrdersList,
+  cmdPricing,
+  cmdProducts,
+  cmdRecipientCheck,
+  cmdWatch,
+  cmdWebhookVerify
+});

package/dist/index.d.cts

@@ -0,0 +1,157 @@
+import { MyStarsClient, OrderType, Currency, OrderStatus } from '@mystars-tg/faas-sdk';
+
+/**
+ * CLI command handlers — pure-ish functions that take a client + parsed options +
+ * an IO sink, so they're unit-testable without spawning a process.
+ */
+
+/**
+ * The IO sink a command writes to — injected so commands are unit-testable
+ * without touching the real process streams. The `mystars-faas` bin wires
+ * `out` to stdout and `err` to stderr.
+ */
+interface CliIO {
+    /** Primary (machine-readable) output — pretty-printed JSON goes here. */
+    out: (line: string) => void;
+    /** Diagnostics / progress (e.g. status updates from `watch`) go here. */
+    err: (line: string) => void;
+}
+/**
+ * `pricing` — quote the all-in price for an item and print the `PricingQuote` JSON.
+ *
+ * @param client - a configured {@link MyStarsClient}
+ * @param opts - `type` plus `quantity` (stars) or `months` (premium), and an optional `currency`
+ * @param io - the output sink
+ * @returns resolves once the quote has been printed
+ * @throws `MyStarsValidationError` if `quantity`/`months` is out of range
+ * @throws `MyStarsApiError` on an API failure (e.g. 503 when a price source is down)
+ */
+declare function cmdPricing(client: MyStarsClient, opts: {
+    type: OrderType;
+    quantity?: number;
+    months?: number;
+    currency?: Currency;
+}, io: CliIO): Promise<void>;
+/**
+ * `products` — print the price-free product catalog (`GET /v1/products`).
+ *
+ * @param client - a configured {@link MyStarsClient}
+ * @param io - the output sink
+ * @returns resolves once the catalog has been printed
+ * @throws `MyStarsApiError` on an API failure
+ */
+declare function cmdProducts(client: MyStarsClient, io: CliIO): Promise<void>;
+/**
+ * `currencies` — print the supported on-chain payment currencies (`GET /v1/currencies`).
+ *
+ * @param client - a configured {@link MyStarsClient}
+ * @param io - the output sink
+ * @returns resolves once the currency list has been printed
+ * @throws `MyStarsApiError` on an API failure
+ */
+declare function cmdCurrencies(client: MyStarsClient, io: CliIO): Promise<void>;
+/**
+ * `recipient-check` — resolve a `@username` and print eligibility (`POST /v1/recipients/check`).
+ *
+ * @param client - a configured {@link MyStarsClient}
+ * @param opts - `type`, the `username` (with or without a leading `@`), and `months` for premium
+ * @param io - the output sink
+ * @returns resolves once the result has been printed
+ * @throws `MyStarsValidationError` if the username is malformed
+ * @throws `MyStarsApiError` on an API failure
+ */
+declare function cmdRecipientCheck(client: MyStarsClient, opts: {
+    type: OrderType;
+    username: string;
+    months?: number;
+}, io: CliIO): Promise<void>;
+/**
+ * `orders create` — create an order (`POST /v1/orders`) and print it. With
+ * `pay: true` it also prints a non-custodial `payment_request` (deeplink / QR /
+ * TON Connect) built from the order's payment block.
+ *
+ * NOTE: the CLI does not pass a stable idempotency key, so the client mints a
+ * fresh uuid per invocation — fine for interactive one-offs, but for scripted /
+ * automated creation prefer the SDK with a caller-stable `idempotencyKey`.
+ *
+ * @param client - a configured {@link MyStarsClient}
+ * @param opts - `type`, `recipient` username, sizing (`quantity`/`months`), optional `currency`, `callback` URL, and `pay` to also emit a payment request
+ * @param io - the output sink
+ * @returns resolves once the order (and optional payment request) has been printed
+ * @throws `MyStarsValidationError` if inputs are invalid
+ * @throws `RecipientIneligibleError` (422) if the recipient cannot receive the item
+ * @throws `MyStarsApiError` on any other API failure
+ */
+declare function cmdOrdersCreate(client: MyStarsClient, opts: {
+    type: OrderType;
+    recipient: string;
+    quantity?: number;
+    months?: number;
+    currency?: Currency;
+    callback?: string;
+    pay?: boolean;
+}, io: CliIO): Promise<void>;
+/**
+ * `orders get` — fetch one order by id (`GET /v1/orders/:id`) and print it.
+ *
+ * @param client - a configured {@link MyStarsClient}
+ * @param id - the order UUID
+ * @param io - the output sink
+ * @returns resolves once the order has been printed
+ * @throws `NotFoundError` (404) if no such order exists for this tenant
+ * @throws `MyStarsApiError` on any other API failure
+ */
+declare function cmdOrdersGet(client: MyStarsClient, id: string, io: CliIO): Promise<void>;
+/**
+ * `orders list` — print a SINGLE page of orders (`GET /v1/orders`), optionally
+ * filtered by `status`. (The CLI prints one page; use the SDK's `listOrders`
+ * async iterator to walk every page.)
+ *
+ * @param client - a configured {@link MyStarsClient}
+ * @param opts - optional `status` filter and `limit` (1-100, server default 50)
+ * @param io - the output sink
+ * @returns resolves once the page has been printed
+ * @throws `MyStarsApiError` on an API failure
+ */
+declare function cmdOrdersList(client: MyStarsClient, opts: {
+    status?: OrderStatus;
+    limit?: number;
+}, io: CliIO): Promise<void>;
+/**
+ * `orders cancel` — cancel an `awaiting_payment` order (`POST /v1/orders/:id/cancel`) and print the result.
+ *
+ * @param client - a configured {@link MyStarsClient}
+ * @param id - the order UUID
+ * @param io - the output sink
+ * @returns resolves once the cancel result has been printed
+ * @throws `OrderNotCancellableError` (409) if the order is no longer `awaiting_payment`
+ * @throws `MyStarsApiError` on any other API failure
+ */
+declare function cmdOrdersCancel(client: MyStarsClient, id: string, io: CliIO): Promise<void>;
+/**
+ * `watch` — poll an order until it reaches a terminal state, streaming each
+ * status change to `io.err`, then print the final order to `io.out`.
+ *
+ * @param client - a configured {@link MyStarsClient}
+ * @param id - the order UUID
+ * @param io - the output sink (status updates → `err`, final order → `out`)
+ * @returns resolves once the order is terminal and has been printed
+ * @throws `OrderWaitTimeoutError` if the order does not finish before the default deadline
+ * @throws `MyStarsApiError` on an API failure during polling
+ */
+declare function cmdWatch(client: MyStarsClient, id: string, io: CliIO): Promise<void>;
+/**
+ * `webhook-verify` — verify an `X-Faas-Signature` over a raw webhook body and
+ * print `{ valid: boolean }`. Does NOT need a client (offline HMAC check).
+ *
+ * @param opts - the tenant `secret`, the raw `body` string, and the `signature` header value
+ * @param io - the output sink
+ * @returns resolves once `{ valid }` has been printed (never throws on a bad signature — it prints `false`)
+ */
+declare function cmdWebhookVerify(opts: {
+    secret: string;
+    body: string;
+    signature: string;
+}, io: CliIO): Promise<void>;
+
+export { type CliIO, cmdCurrencies, cmdOrdersCancel, cmdOrdersCreate, cmdOrdersGet, cmdOrdersList, cmdPricing, cmdProducts, cmdRecipientCheck, cmdWatch, cmdWebhookVerify };

package/dist/index.d.ts

@@ -0,0 +1,157 @@
+import { MyStarsClient, OrderType, Currency, OrderStatus } from '@mystars-tg/faas-sdk';
+
+/**
+ * CLI command handlers — pure-ish functions that take a client + parsed options +
+ * an IO sink, so they're unit-testable without spawning a process.
+ */
+
+/**
+ * The IO sink a command writes to — injected so commands are unit-testable
+ * without touching the real process streams. The `mystars-faas` bin wires
+ * `out` to stdout and `err` to stderr.
+ */
+interface CliIO {
+    /** Primary (machine-readable) output — pretty-printed JSON goes here. */
+    out: (line: string) => void;
+    /** Diagnostics / progress (e.g. status updates from `watch`) go here. */
+    err: (line: string) => void;
+}
+/**
+ * `pricing` — quote the all-in price for an item and print the `PricingQuote` JSON.
+ *
+ * @param client - a configured {@link MyStarsClient}
+ * @param opts - `type` plus `quantity` (stars) or `months` (premium), and an optional `currency`
+ * @param io - the output sink
+ * @returns resolves once the quote has been printed
+ * @throws `MyStarsValidationError` if `quantity`/`months` is out of range
+ * @throws `MyStarsApiError` on an API failure (e.g. 503 when a price source is down)
+ */
+declare function cmdPricing(client: MyStarsClient, opts: {
+    type: OrderType;
+    quantity?: number;
+    months?: number;
+    currency?: Currency;
+}, io: CliIO): Promise<void>;
+/**
+ * `products` — print the price-free product catalog (`GET /v1/products`).
+ *
+ * @param client - a configured {@link MyStarsClient}
+ * @param io - the output sink
+ * @returns resolves once the catalog has been printed
+ * @throws `MyStarsApiError` on an API failure
+ */
+declare function cmdProducts(client: MyStarsClient, io: CliIO): Promise<void>;
+/**
+ * `currencies` — print the supported on-chain payment currencies (`GET /v1/currencies`).
+ *
+ * @param client - a configured {@link MyStarsClient}
+ * @param io - the output sink
+ * @returns resolves once the currency list has been printed
+ * @throws `MyStarsApiError` on an API failure
+ */
+declare function cmdCurrencies(client: MyStarsClient, io: CliIO): Promise<void>;
+/**
+ * `recipient-check` — resolve a `@username` and print eligibility (`POST /v1/recipients/check`).
+ *
+ * @param client - a configured {@link MyStarsClient}
+ * @param opts - `type`, the `username` (with or without a leading `@`), and `months` for premium
+ * @param io - the output sink
+ * @returns resolves once the result has been printed
+ * @throws `MyStarsValidationError` if the username is malformed
+ * @throws `MyStarsApiError` on an API failure
+ */
+declare function cmdRecipientCheck(client: MyStarsClient, opts: {
+    type: OrderType;
+    username: string;
+    months?: number;
+}, io: CliIO): Promise<void>;
+/**
+ * `orders create` — create an order (`POST /v1/orders`) and print it. With
+ * `pay: true` it also prints a non-custodial `payment_request` (deeplink / QR /
+ * TON Connect) built from the order's payment block.
+ *
+ * NOTE: the CLI does not pass a stable idempotency key, so the client mints a
+ * fresh uuid per invocation — fine for interactive one-offs, but for scripted /
+ * automated creation prefer the SDK with a caller-stable `idempotencyKey`.
+ *
+ * @param client - a configured {@link MyStarsClient}
+ * @param opts - `type`, `recipient` username, sizing (`quantity`/`months`), optional `currency`, `callback` URL, and `pay` to also emit a payment request
+ * @param io - the output sink
+ * @returns resolves once the order (and optional payment request) has been printed
+ * @throws `MyStarsValidationError` if inputs are invalid
+ * @throws `RecipientIneligibleError` (422) if the recipient cannot receive the item
+ * @throws `MyStarsApiError` on any other API failure
+ */
+declare function cmdOrdersCreate(client: MyStarsClient, opts: {
+    type: OrderType;
+    recipient: string;
+    quantity?: number;
+    months?: number;
+    currency?: Currency;
+    callback?: string;
+    pay?: boolean;
+}, io: CliIO): Promise<void>;
+/**
+ * `orders get` — fetch one order by id (`GET /v1/orders/:id`) and print it.
+ *
+ * @param client - a configured {@link MyStarsClient}
+ * @param id - the order UUID
+ * @param io - the output sink
+ * @returns resolves once the order has been printed
+ * @throws `NotFoundError` (404) if no such order exists for this tenant
+ * @throws `MyStarsApiError` on any other API failure
+ */
+declare function cmdOrdersGet(client: MyStarsClient, id: string, io: CliIO): Promise<void>;
+/**
+ * `orders list` — print a SINGLE page of orders (`GET /v1/orders`), optionally
+ * filtered by `status`. (The CLI prints one page; use the SDK's `listOrders`
+ * async iterator to walk every page.)
+ *
+ * @param client - a configured {@link MyStarsClient}
+ * @param opts - optional `status` filter and `limit` (1-100, server default 50)
+ * @param io - the output sink
+ * @returns resolves once the page has been printed
+ * @throws `MyStarsApiError` on an API failure
+ */
+declare function cmdOrdersList(client: MyStarsClient, opts: {
+    status?: OrderStatus;
+    limit?: number;
+}, io: CliIO): Promise<void>;
+/**
+ * `orders cancel` — cancel an `awaiting_payment` order (`POST /v1/orders/:id/cancel`) and print the result.
+ *
+ * @param client - a configured {@link MyStarsClient}
+ * @param id - the order UUID
+ * @param io - the output sink
+ * @returns resolves once the cancel result has been printed
+ * @throws `OrderNotCancellableError` (409) if the order is no longer `awaiting_payment`
+ * @throws `MyStarsApiError` on any other API failure
+ */
+declare function cmdOrdersCancel(client: MyStarsClient, id: string, io: CliIO): Promise<void>;
+/**
+ * `watch` — poll an order until it reaches a terminal state, streaming each
+ * status change to `io.err`, then print the final order to `io.out`.
+ *
+ * @param client - a configured {@link MyStarsClient}
+ * @param id - the order UUID
+ * @param io - the output sink (status updates → `err`, final order → `out`)
+ * @returns resolves once the order is terminal and has been printed
+ * @throws `OrderWaitTimeoutError` if the order does not finish before the default deadline
+ * @throws `MyStarsApiError` on an API failure during polling
+ */
+declare function cmdWatch(client: MyStarsClient, id: string, io: CliIO): Promise<void>;
+/**
+ * `webhook-verify` — verify an `X-Faas-Signature` over a raw webhook body and
+ * print `{ valid: boolean }`. Does NOT need a client (offline HMAC check).
+ *
+ * @param opts - the tenant `secret`, the raw `body` string, and the `signature` header value
+ * @param io - the output sink
+ * @returns resolves once `{ valid }` has been printed (never throws on a bad signature — it prints `false`)
+ */
+declare function cmdWebhookVerify(opts: {
+    secret: string;
+    body: string;
+    signature: string;
+}, io: CliIO): Promise<void>;
+
+export { type CliIO, cmdCurrencies, cmdOrdersCancel, cmdOrdersCreate, cmdOrdersGet, cmdOrdersList, cmdPricing, cmdProducts, cmdRecipientCheck, cmdWatch, cmdWebhookVerify };

package/dist/index.js

@@ -0,0 +1,24 @@
+import {
+  cmdCurrencies,
+  cmdOrdersCancel,
+  cmdOrdersCreate,
+  cmdOrdersGet,
+  cmdOrdersList,
+  cmdPricing,
+  cmdProducts,
+  cmdRecipientCheck,
+  cmdWatch,
+  cmdWebhookVerify
+} from "./chunk-LVDNP4X2.js";
+export {
+  cmdCurrencies,
+  cmdOrdersCancel,
+  cmdOrdersCreate,
+  cmdOrdersGet,
+  cmdOrdersList,
+  cmdPricing,
+  cmdProducts,
+  cmdRecipientCheck,
+  cmdWatch,
+  cmdWebhookVerify
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@mystars-tg/faas-cli",
+  "version": "0.1.2",
+  "description": "Command-line tool for the MyStars FaaS API — pricing, recipient checks, order management, payment links, and webhook verification.",
+  "license": "MIT",
+  "author": "MyStars.tg",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["telegram", "stars", "premium", "ton", "usdt", "mystars", "faas", "cli"],
+  "homepage": "https://mystars.tg/docs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mystars-tg/faas-ts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mystars-tg/faas-ts/issues"
+  },
+  "bin": {
+    "mystars-faas": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --root ../..",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@mystars-tg/faas-sdk": "^0.1.2",
+    "commander": "^12.1.0"
+  }
+}