@roxyon/api-client 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -81,7 +81,8 @@ declare class RoxyonClient {
     del<T = unknown>(path: string, body?: unknown, opts?: RequestOptions): Promise<T>;
 }
 
-type TokenScope = 'deploy' | 'logs' | 'read';
+/** `billing:order` lets the token place orders (human pays) within its monthly budget; never a default. */
+type TokenScope = 'deploy' | 'logs' | 'read' | 'billing:order';
 interface TokenSummary {
     id: string;
     name: string;
@@ -90,6 +91,10 @@ interface TokenSummary {
     lastUsedAt: string | null;
     expiresAt: string | null;
     createdAt: string;
+    /** For `billing:order` tokens: the most it may order per calendar month, in USD before tax. */
+    monthlyBudgetUSD?: number | null;
+    /** For `billing:order` tokens: plan codes it may order (empty = any). */
+    allowedSkus?: string[];
 }
 interface CreatedToken {
     /** The full `roxp_…` secret — shown once. Use it as `ROXYON_TOKEN`. */
@@ -112,6 +117,9 @@ declare class TokensApi {
     create(name: string, opts?: {
         scopes?: TokenScope[];
         expiresInDays?: number;
+        /** Required with `billing:order`. */
+        monthlyBudgetUSD?: number;
+        allowedSkus?: string[];
     }): Promise<CreatedToken>;
     revoke(id: string): Promise<void>;
 }
@@ -419,6 +427,48 @@ interface Quote {
     fxRate: string;
     baseAmountUSD: string;
 }
+interface OrderInput {
+    /** Plan code from the catalog, e.g. `SCALE-S`. */
+    sku: string;
+    cycle: BillingCycle;
+    /** A name for the service. */
+    name: string;
+    /** Account / server name: 2-63 lowercase letters, digits, dots, dashes; must be free. */
+    username: string;
+    /** Servers only: OS image, e.g. `ubuntu-24.04`. */
+    image?: string;
+    sshKey?: string;
+    phpVersion?: string;
+    datacenter?: string;
+    currency?: string;
+    country?: string;
+    /** false/absent = dry run (quote + budget check, nothing written). */
+    confirm?: boolean;
+}
+interface OrderBudget {
+    monthlyUSD: number;
+    spentUSD: number;
+    remainingUSD: number;
+}
+interface OrderResult {
+    dryRun?: boolean;
+    plan: {
+        id: string;
+        sku: string;
+        name: string;
+        kind: 'hosting' | 'server';
+        cycle: string;
+    };
+    /** Dry run: the server quote (same shape as GET /_payment/quote). */
+    quote?: Record<string, unknown>;
+    subscriptionId?: string;
+    invoiceId?: string;
+    total?: string;
+    currency?: string;
+    payUrl?: string;
+    /** null for a console session (no token budget). */
+    budget: OrderBudget | null;
+}
 interface BillingSubscription {
     id: string;
     name: string;
@@ -459,6 +509,12 @@ declare class BillingApi {
     catalog(): Promise<CatalogProduct[]>;
     /** What checkout would charge for a new subscription: the server's own pricing (GET /_payment/quote). */
     quote(input: QuoteInput): Promise<Quote>;
+    /**
+     * A new order for the caller (POST /account/order): dry run unless `confirm`. The engine prices and creates it
+     * (Subscription in payment + pending invoice); a person pays at `payUrl`. Needs a session or a PAT with the
+     * `billing:order` scope, within that token's monthly budget and allowed SKUs.
+     */
+    order(input: OrderInput): Promise<OrderResult>;
     /** The caller's own subscriptions (rows they own), newest first. */
     subscriptions(): Promise<BillingSubscription[]>;
     /** The caller's own invoices, newest first. */
@@ -504,6 +560,7 @@ interface DeleteDatabaseResult {
 declare class DatabasesApi {
     private readonly client;
     constructor(client: RoxyonClient);
+    /** `POST /databases/list` — through the console, because PAT/OAuth callers can't read /Databases directly. */
     list(subscriptionId: string): Promise<DatabaseSummary[]>;
     /** `POST /databases/create` — provision a database + user; the reconciler does the rest. */
     create(input: CreateDatabaseInput): Promise<CreateDatabaseResult>;
@@ -587,6 +644,7 @@ interface DeleteEmailResult {
 declare class EmailApi {
     private readonly client;
     constructor(client: RoxyonClient);
+    /** `POST /emails/list` — through the console, because PAT/OAuth callers can't read /Emails directly. */
     list(subscriptionId: string): Promise<EmailSummary[]>;
     /** `POST /emails/create` — provision a mailbox; the reconciler does the rest. */
     create(input: CreateEmailInput): Promise<CreateEmailResult>;
@@ -874,4 +932,4 @@ declare class Roxyon {
     get sessionToken(): string | undefined;
 }
 
-export { AccountApi, type AccountApp, type AccountContext, type AccountDomain, type AccountSubscription, type Application, type ApplicationProcess, type ApplicationRoute, ApplicationsApi, AuthApi, BAAS_MAX_BATCH, BAAS_MAX_PAGE, BILLING_CYCLES, type BaasBatchRequest, type BaasBatchResult, BaasDataApi, type BaasDataOptions, type BaasQuery, type BaasRow, BillingApi, type BillingCycle, type BillingSubscription, type CatalogProduct, type CreateApplicationInput, type CreateDatabaseInput, type CreateDatabaseResult, type CreateDomainInput, type CreateDomainResult, type CreateEmailInput, type CreateEmailResult, type CreateOnDeploy, type CreatedToken, DEFAULT_APP, DEFAULT_BAAS_URL, DEFAULT_BAAS_V2_URL, DEFAULT_CONSOLE_URL, type DatabaseSummary, DatabasesApi, type DeleteDatabaseResult, type DeleteEmailResult, type DeployKind, type DeployOptions, type DeployResult, type Domain, DomainsApi, EmailApi, type EmailSummary, type Invoice, LUMEN_BUILD, type LoginPrecheck, type LoginResult, PAYABLE_STATUSES, type Privilege, type Quote, type QuoteInput, RUNTIMES, type RequestOptions, type ResetSshPasswordInput, type ResetSshPasswordResult, Roxyon, RoxyonApiError, RoxyonClient, type RoxyonClientOptions, type RoxyonUser, type RuntimeName, type RuntimeSpec, type SessionGrant, type SiteFile, type SiteFileContent, SitesApi, SshApi, type StaticDeployResult, type Subscription, SubscriptionsApi, type TokenScope, type TokenSummary, TokensApi, assertOk, envFromStored, formatEnv, isAuthError, isPayable, parseEnv, rxError, toQueryString };
+export { AccountApi, type AccountApp, type AccountContext, type AccountDomain, type AccountSubscription, type Application, type ApplicationProcess, type ApplicationRoute, ApplicationsApi, AuthApi, BAAS_MAX_BATCH, BAAS_MAX_PAGE, BILLING_CYCLES, type BaasBatchRequest, type BaasBatchResult, BaasDataApi, type BaasDataOptions, type BaasQuery, type BaasRow, BillingApi, type BillingCycle, type BillingSubscription, type CatalogProduct, type CreateApplicationInput, type CreateDatabaseInput, type CreateDatabaseResult, type CreateDomainInput, type CreateDomainResult, type CreateEmailInput, type CreateEmailResult, type CreateOnDeploy, type CreatedToken, DEFAULT_APP, DEFAULT_BAAS_URL, DEFAULT_BAAS_V2_URL, DEFAULT_CONSOLE_URL, type DatabaseSummary, DatabasesApi, type DeleteDatabaseResult, type DeleteEmailResult, type DeployKind, type DeployOptions, type DeployResult, type Domain, DomainsApi, EmailApi, type EmailSummary, type Invoice, LUMEN_BUILD, type LoginPrecheck, type LoginResult, type OrderBudget, type OrderInput, type OrderResult, PAYABLE_STATUSES, type Privilege, type Quote, type QuoteInput, RUNTIMES, type RequestOptions, type ResetSshPasswordInput, type ResetSshPasswordResult, Roxyon, RoxyonApiError, RoxyonClient, type RoxyonClientOptions, type RoxyonUser, type RuntimeName, type RuntimeSpec, type SessionGrant, type SiteFile, type SiteFileContent, SitesApi, SshApi, type StaticDeployResult, type Subscription, SubscriptionsApi, type TokenScope, type TokenSummary, TokensApi, assertOk, envFromStored, formatEnv, isAuthError, isPayable, parseEnv, rxError, toQueryString };

package/dist/index.d.ts

@@ -81,7 +81,8 @@ declare class RoxyonClient {
     del<T = unknown>(path: string, body?: unknown, opts?: RequestOptions): Promise<T>;
 }
 
-type TokenScope = 'deploy' | 'logs' | 'read';
+/** `billing:order` lets the token place orders (human pays) within its monthly budget; never a default. */
+type TokenScope = 'deploy' | 'logs' | 'read' | 'billing:order';
 interface TokenSummary {
     id: string;
     name: string;
@@ -90,6 +91,10 @@ interface TokenSummary {
     lastUsedAt: string | null;
     expiresAt: string | null;
     createdAt: string;
+    /** For `billing:order` tokens: the most it may order per calendar month, in USD before tax. */
+    monthlyBudgetUSD?: number | null;
+    /** For `billing:order` tokens: plan codes it may order (empty = any). */
+    allowedSkus?: string[];
 }
 interface CreatedToken {
     /** The full `roxp_…` secret — shown once. Use it as `ROXYON_TOKEN`. */
@@ -112,6 +117,9 @@ declare class TokensApi {
     create(name: string, opts?: {
         scopes?: TokenScope[];
         expiresInDays?: number;
+        /** Required with `billing:order`. */
+        monthlyBudgetUSD?: number;
+        allowedSkus?: string[];
     }): Promise<CreatedToken>;
     revoke(id: string): Promise<void>;
 }
@@ -419,6 +427,48 @@ interface Quote {
     fxRate: string;
     baseAmountUSD: string;
 }
+interface OrderInput {
+    /** Plan code from the catalog, e.g. `SCALE-S`. */
+    sku: string;
+    cycle: BillingCycle;
+    /** A name for the service. */
+    name: string;
+    /** Account / server name: 2-63 lowercase letters, digits, dots, dashes; must be free. */
+    username: string;
+    /** Servers only: OS image, e.g. `ubuntu-24.04`. */
+    image?: string;
+    sshKey?: string;
+    phpVersion?: string;
+    datacenter?: string;
+    currency?: string;
+    country?: string;
+    /** false/absent = dry run (quote + budget check, nothing written). */
+    confirm?: boolean;
+}
+interface OrderBudget {
+    monthlyUSD: number;
+    spentUSD: number;
+    remainingUSD: number;
+}
+interface OrderResult {
+    dryRun?: boolean;
+    plan: {
+        id: string;
+        sku: string;
+        name: string;
+        kind: 'hosting' | 'server';
+        cycle: string;
+    };
+    /** Dry run: the server quote (same shape as GET /_payment/quote). */
+    quote?: Record<string, unknown>;
+    subscriptionId?: string;
+    invoiceId?: string;
+    total?: string;
+    currency?: string;
+    payUrl?: string;
+    /** null for a console session (no token budget). */
+    budget: OrderBudget | null;
+}
 interface BillingSubscription {
     id: string;
     name: string;
@@ -459,6 +509,12 @@ declare class BillingApi {
     catalog(): Promise<CatalogProduct[]>;
     /** What checkout would charge for a new subscription: the server's own pricing (GET /_payment/quote). */
     quote(input: QuoteInput): Promise<Quote>;
+    /**
+     * A new order for the caller (POST /account/order): dry run unless `confirm`. The engine prices and creates it
+     * (Subscription in payment + pending invoice); a person pays at `payUrl`. Needs a session or a PAT with the
+     * `billing:order` scope, within that token's monthly budget and allowed SKUs.
+     */
+    order(input: OrderInput): Promise<OrderResult>;
     /** The caller's own subscriptions (rows they own), newest first. */
     subscriptions(): Promise<BillingSubscription[]>;
     /** The caller's own invoices, newest first. */
@@ -504,6 +560,7 @@ interface DeleteDatabaseResult {
 declare class DatabasesApi {
     private readonly client;
     constructor(client: RoxyonClient);
+    /** `POST /databases/list` — through the console, because PAT/OAuth callers can't read /Databases directly. */
     list(subscriptionId: string): Promise<DatabaseSummary[]>;
     /** `POST /databases/create` — provision a database + user; the reconciler does the rest. */
     create(input: CreateDatabaseInput): Promise<CreateDatabaseResult>;
@@ -587,6 +644,7 @@ interface DeleteEmailResult {
 declare class EmailApi {
     private readonly client;
     constructor(client: RoxyonClient);
+    /** `POST /emails/list` — through the console, because PAT/OAuth callers can't read /Emails directly. */
     list(subscriptionId: string): Promise<EmailSummary[]>;
     /** `POST /emails/create` — provision a mailbox; the reconciler does the rest. */
     create(input: CreateEmailInput): Promise<CreateEmailResult>;
@@ -874,4 +932,4 @@ declare class Roxyon {
     get sessionToken(): string | undefined;
 }
 
-export { AccountApi, type AccountApp, type AccountContext, type AccountDomain, type AccountSubscription, type Application, type ApplicationProcess, type ApplicationRoute, ApplicationsApi, AuthApi, BAAS_MAX_BATCH, BAAS_MAX_PAGE, BILLING_CYCLES, type BaasBatchRequest, type BaasBatchResult, BaasDataApi, type BaasDataOptions, type BaasQuery, type BaasRow, BillingApi, type BillingCycle, type BillingSubscription, type CatalogProduct, type CreateApplicationInput, type CreateDatabaseInput, type CreateDatabaseResult, type CreateDomainInput, type CreateDomainResult, type CreateEmailInput, type CreateEmailResult, type CreateOnDeploy, type CreatedToken, DEFAULT_APP, DEFAULT_BAAS_URL, DEFAULT_BAAS_V2_URL, DEFAULT_CONSOLE_URL, type DatabaseSummary, DatabasesApi, type DeleteDatabaseResult, type DeleteEmailResult, type DeployKind, type DeployOptions, type DeployResult, type Domain, DomainsApi, EmailApi, type EmailSummary, type Invoice, LUMEN_BUILD, type LoginPrecheck, type LoginResult, PAYABLE_STATUSES, type Privilege, type Quote, type QuoteInput, RUNTIMES, type RequestOptions, type ResetSshPasswordInput, type ResetSshPasswordResult, Roxyon, RoxyonApiError, RoxyonClient, type RoxyonClientOptions, type RoxyonUser, type RuntimeName, type RuntimeSpec, type SessionGrant, type SiteFile, type SiteFileContent, SitesApi, SshApi, type StaticDeployResult, type Subscription, SubscriptionsApi, type TokenScope, type TokenSummary, TokensApi, assertOk, envFromStored, formatEnv, isAuthError, isPayable, parseEnv, rxError, toQueryString };
+export { AccountApi, type AccountApp, type AccountContext, type AccountDomain, type AccountSubscription, type Application, type ApplicationProcess, type ApplicationRoute, ApplicationsApi, AuthApi, BAAS_MAX_BATCH, BAAS_MAX_PAGE, BILLING_CYCLES, type BaasBatchRequest, type BaasBatchResult, BaasDataApi, type BaasDataOptions, type BaasQuery, type BaasRow, BillingApi, type BillingCycle, type BillingSubscription, type CatalogProduct, type CreateApplicationInput, type CreateDatabaseInput, type CreateDatabaseResult, type CreateDomainInput, type CreateDomainResult, type CreateEmailInput, type CreateEmailResult, type CreateOnDeploy, type CreatedToken, DEFAULT_APP, DEFAULT_BAAS_URL, DEFAULT_BAAS_V2_URL, DEFAULT_CONSOLE_URL, type DatabaseSummary, DatabasesApi, type DeleteDatabaseResult, type DeleteEmailResult, type DeployKind, type DeployOptions, type DeployResult, type Domain, DomainsApi, EmailApi, type EmailSummary, type Invoice, LUMEN_BUILD, type LoginPrecheck, type LoginResult, type OrderBudget, type OrderInput, type OrderResult, PAYABLE_STATUSES, type Privilege, type Quote, type QuoteInput, RUNTIMES, type RequestOptions, type ResetSshPasswordInput, type ResetSshPasswordResult, Roxyon, RoxyonApiError, RoxyonClient, type RoxyonClientOptions, type RoxyonUser, type RuntimeName, type RuntimeSpec, type SessionGrant, type SiteFile, type SiteFileContent, SitesApi, SshApi, type StaticDeployResult, type Subscription, SubscriptionsApi, type TokenScope, type TokenSummary, TokensApi, assertOk, envFromStored, formatEnv, isAuthError, isPayable, parseEnv, rxError, toQueryString };

package/dist/index.js

@@ -443,7 +443,7 @@ var BillingApi = class {
         {
           className: "Pricing",
           field: "Plan",
-          fields: "Prices,SetupFee,MetaData",
+          fields: "Prices,SetupFee,MetaData,IsActive",
           reverse: 1
         }
       ]
@@ -454,18 +454,20 @@ var BillingApi = class {
     const out = [];
     for (const p of r.results) {
       const pricing = p._Pricing?.results?.[0];
-      if (!pricing) continue;
+      if (!p.Code || !pricing || Number(pricing.IsActive) === 0) continue;
       const limits = json(p.Limits, {});
       const features = json(p.Features, {});
       const meta = json(pricing.MetaData, {});
       const network = json(features.Network, {});
       const setup = numbers(pricing.SetupFee);
+      const pricesUSD = numbers(pricing.Prices);
+      if (pricesUSD.monthly === void 0) continue;
       const product = {
         planId: p.objectId,
         sku: p.Code ?? "",
         name: p.Name ?? "",
         category: p._Service?.results?.[0]?.Type ?? "",
-        pricesUSD: numbers(pricing.Prices),
+        pricesUSD,
         stock: String(meta.stock ?? "in").toLowerCase() === "out" ? "out" : "in"
       };
       if (limits.vcpu != null) {
@@ -517,6 +519,16 @@ var BillingApi = class {
       baseAmountUSD: String(r.baseAmount ?? "")
     };
   }
+  /**
+   * A new order for the caller (POST /account/order): dry run unless `confirm`. The engine prices and creates it
+   * (Subscription in payment + pending invoice); a person pays at `payUrl`. Needs a session or a PAT with the
+   * `billing:order` scope, within that token's monthly budget and allowed SKUs.
+   */
+  async order(input) {
+    const r = await this.client.console("POST", "/account/order", { body: input, tolerateHttpError: true });
+    if (!r?.ok) throw new RoxyonApiError(r?.error || "The order was not placed.", { body: r });
+    return r;
+  }
   /** The caller's own subscriptions (rows they own), newest first. */
   async subscriptions() {
     const r = await this.client.console("GET", "/account/subscriptions", { tolerateHttpError: true });
@@ -702,7 +714,11 @@ var RoxyonClient = class _RoxyonClient {
     try {
       json2 = text ? JSON.parse(text) : {};
     } catch {
-      json2 = { error: text || `HTTP ${res.status}`, _raw: text };
+      const html = /^\s*</.test(text);
+      json2 = {
+        error: html ? `${method} ${path} is not available on this server yet (got a web page instead of the API).` : text || `HTTP ${res.status}`,
+        _raw: html ? "" : text
+      };
     }
     if (!res.ok && !opts.tolerateHttpError) {
       const msg = json2 && typeof json2 === "object" && "error" in json2 && json2.error || `HTTP ${res.status} calling ${method} ${path}`;
@@ -730,14 +746,14 @@ var DatabasesApi = class {
     this.client = client;
   }
   client;
+  /** `POST /databases/list` — through the console, because PAT/OAuth callers can't read /Databases directly. */
   async list(subscriptionId) {
-    const r = await this.client.get("/Databases", {
-      fields: "objectId,Name,Username,Status",
-      limit: -1,
-      order: "-createdAt",
-      where: { Subscription: subscriptionId, eye: { in: "1,0" } }
+    const r = await this.client.console("POST", "/databases/list", {
+      body: { subscription: subscriptionId },
+      tolerateHttpError: true
     });
-    return r.results ?? [];
+    if (!r?.ok) throw new RoxyonApiError(r?.error || "Could not list the databases.", { body: r });
+    return r.databases ?? [];
   }
   /** `POST /databases/create` — provision a database + user; the reconciler does the rest. */
   async create(input) {
@@ -795,14 +811,11 @@ var EmailApi = class {
     this.client = client;
   }
   client;
+  /** `POST /emails/list` — through the console, because PAT/OAuth callers can't read /Emails directly. */
   async list(subscriptionId) {
-    const r = await this.client.get("/Emails", {
-      fields: "objectId,Email,LocalPart,Status,Quota",
-      limit: -1,
-      order: "-createdAt",
-      where: { Subscription: subscriptionId, eye: { in: "1,0" } }
-    });
-    return r.results ?? [];
+    const r = await this.client.console("POST", "/emails/list", { body: { subscription: subscriptionId }, tolerateHttpError: true });
+    if (!r?.ok) throw new RoxyonApiError(r?.error || "Could not list the mailboxes.", { body: r });
+    return (r.emails ?? []).map((e) => ({ ...e, LocalPart: e.Email.split("@")[0] ?? "" }));
   }
   /** `POST /emails/create` — provision a mailbox; the reconciler does the rest. */
   async create(input) {
@@ -971,7 +984,9 @@ var TokensApi = class {
         body: {
           name,
           scopes: opts.scopes ?? ["deploy", "logs"],
-          ...opts.expiresInDays ? { expiresInDays: opts.expiresInDays } : {}
+          ...opts.expiresInDays ? { expiresInDays: opts.expiresInDays } : {},
+          ...opts.monthlyBudgetUSD ? { monthlyBudgetUSD: opts.monthlyBudgetUSD } : {},
+          ...opts.allowedSkus?.length ? { allowedSkus: opts.allowedSkus } : {}
         },
         tolerateHttpError: true
       }