@roxyon/api-client 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -59,6 +59,9 @@ declare class RoxyonClient {
     private sessionToken?;
     private anon?;
     constructor(opts?: RoxyonClientOptions);
+    /** Same endpoints and app, no user credentials: for public reads (catalog, quotes)
+     * that must work for PAT callers too, whose token the BaaS does not accept. */
+    publicClient(): RoxyonClient;
     getSessionToken(): string | undefined;
     setSessionToken(token: string | undefined): void;
     /** Mint (or reuse) an anonymous access token from the public app credentials. */
@@ -364,6 +367,107 @@ declare class AuthApi {
     logout(): Promise<void>;
 }
 
+/** Billing cycles the checkout accepts (Pricing::CYCLE_MONTHS). */
+declare const BILLING_CYCLES: readonly ["monthly", "quarterly", "yearly", "biennial"];
+type BillingCycle = (typeof BILLING_CYCLES)[number];
+interface CatalogProduct {
+    /** Plan objectId: what quotes and orders take. */
+    planId: string;
+    /** Plan code, e.g. `SCALE-S`. */
+    sku: string;
+    name: string;
+    /** Service type, e.g. `cloud.vps.scale`, `cloud.hosting.solo`. */
+    category: string;
+    vcpu?: number;
+    ramGb?: number;
+    diskGb?: number;
+    cpuType?: string;
+    /** Dedicated IPv4 addresses included (servers). */
+    ipv4Included?: number;
+    /** List prices in USD before tax, per cycle. Quote for the buyer's currency and tax. */
+    pricesUSD: Partial<Record<BillingCycle, number>>;
+    /** Setup fee in USD per cycle, when not zero. */
+    setupFeeUSD?: Partial<Record<BillingCycle, number>>;
+    /** `out` = cannot be ordered right now. */
+    stock: 'in' | 'out';
+    /** Feature table as the console shows it. */
+    features?: Record<string, unknown>;
+}
+interface QuoteInput {
+    planId: string;
+    cycle: BillingCycle;
+    /** ISO 4217, e.g. `SAR`. Default USD. */
+    currency?: string;
+    /** ISO 3166 alpha-2, decides tax (e.g. `SA` = 15% VAT). Empty = no tax line. */
+    country?: string;
+}
+interface Quote {
+    planId: string;
+    cycle: string;
+    currency: string;
+    lineItems: Array<{
+        label: string;
+        amount: string;
+        amountUSD: string;
+    }>;
+    subtotal: string;
+    taxRate: string;
+    taxLabel: string;
+    taxAmount: string;
+    discountAmount: string;
+    total: string;
+    fxRate: string;
+    baseAmountUSD: string;
+}
+interface BillingSubscription {
+    id: string;
+    name: string;
+    status: string;
+    plan: string;
+    sku: string;
+    cycle: string;
+    price: string;
+    currency: string;
+    nextBillingDate: string | null;
+    autoRenew: boolean;
+    serverState: string | null;
+    publicIp: string | null;
+}
+interface Invoice {
+    id: string;
+    number: string;
+    type: string;
+    status: string;
+    total: string;
+    currency: string;
+    dueDate: string | null;
+    subscription: string | null;
+    createdAt: string;
+    payUrl: string | null;
+}
+/** Invoice statuses a customer can still pay. */
+declare const PAYABLE_STATUSES: readonly ["pending", "overdue", "failed"];
+declare function isPayable(status: string): boolean;
+/**
+ * Catalog + quotes (public, no sign-in) and the caller's own subscriptions + invoices
+ * (console, session or PAT). Read-only: nothing here creates orders or invoices.
+ */
+declare class BillingApi {
+    private readonly client;
+    private readonly pub;
+    constructor(client: RoxyonClient, pub?: RoxyonClient);
+    catalog(): Promise<CatalogProduct[]>;
+    /** What checkout would charge for a new subscription: the server's own pricing (GET /_payment/quote). */
+    quote(input: QuoteInput): Promise<Quote>;
+    /** The caller's own subscriptions (rows they own), newest first. */
+    subscriptions(): Promise<BillingSubscription[]>;
+    /** The caller's own invoices, newest first. */
+    invoices(opts?: {
+        status?: string;
+        limit?: number;
+    }): Promise<Invoice[]>;
+}
+
 interface CreateDatabaseInput {
     /** DB name suffix — the platform prefixes it with the subscription's own username (globally unique). */
     name: string;
@@ -586,6 +690,76 @@ declare class SubscriptionsApi {
     resolve(userId: string, preferred?: string): Promise<Subscription>;
 }
 
+/** BaaS V2 base. V1 (`/1`) is frozen; app data tools speak V2 only. */
+declare const DEFAULT_BAAS_V2_URL = "https://www.beaapis.com/2";
+/** V2 caps one page at 200 rows. */
+declare const BAAS_MAX_PAGE = 200;
+/** V2 takes 1 to 50 requests per batch. */
+declare const BAAS_MAX_BATCH = 50;
+interface BaasDataOptions {
+    /** The app's secret key (`rxsk_…`): server scope, from the project's API keys in Roxyon Base. */
+    secretKey: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+type BaasRow = Record<string, unknown>;
+interface BaasQuery {
+    /** e.g. `{ Status: 'active', Age: { gt: 18 } }`; `in` takes a comma-joined string. */
+    where?: Record<string, unknown>;
+    /** `*` and/or column names, comma separated. Defaults to `*`. */
+    fields?: string;
+    /** Comma list, `-` for descending, e.g. `-createdAt`. */
+    order?: string;
+    /** 1 to 200 (default 50). */
+    limit?: number;
+    skip?: number;
+    /** Also return the total number of matching rows. */
+    count?: boolean;
+}
+interface BaasBatchRequest {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** `/Class` or `/Class/<id>`. */
+    path: string;
+    body?: Record<string, unknown>;
+}
+/** One batch answer: `ok:false` with `error`/`message`, or that request's own V2 answer. */
+interface BaasBatchResult {
+    status: number;
+    ok?: boolean;
+    error?: string;
+    message?: string;
+    result?: BaasRow;
+    results?: BaasRow[];
+    count?: number;
+    id?: string;
+}
+/**
+ * Records of ONE app on BaaS V2, as that app's own backend (server scope, `X-RX-Secret-Key`).
+ * Server scope passes every class rule, so treat the key like a database password. V2 answers
+ * failures as `{ok:false, error, message}` with an HTTP status; every call throws on those.
+ * Schema changes are not reachable with a secret key (console API only).
+ */
+declare class BaasDataApi {
+    private readonly baseUrl;
+    private readonly secretKey;
+    private readonly _fetch;
+    constructor(opts: BaasDataOptions);
+    private call;
+    private static recordPath;
+    query(className: string, q?: BaasQuery): Promise<{
+        rows: BaasRow[];
+        count?: number;
+    }>;
+    get(className: string, objectId: string): Promise<BaasRow>;
+    /** Returns the created row as stored. */
+    create(className: string, data: BaasRow): Promise<BaasRow>;
+    update(className: string, objectId: string, data: BaasRow): Promise<BaasRow>;
+    /** The id goes in the URL path, never the body. */
+    delete(className: string, objectId: string): Promise<void>;
+    /** 1 to 50 record requests in one call; one failing doesn't stop the others. */
+    batch(requests: BaasBatchRequest[]): Promise<BaasBatchResult[]>;
+}
+
 /** Returns the error message from a BaaS response, or `''` when the call worked. */
 declare function rxError(r: unknown): string;
 declare class RoxyonApiError extends Error {
@@ -695,8 +869,9 @@ declare class Roxyon {
     readonly databases: DatabasesApi;
     readonly email: EmailApi;
     readonly ssh: SshApi;
+    readonly billing: BillingApi;
     constructor(options?: RoxyonClientOptions | RoxyonClient);
     get sessionToken(): string | undefined;
 }
 
-export { AccountApi, type AccountApp, type AccountContext, type AccountDomain, type AccountSubscription, type Application, type ApplicationProcess, type ApplicationRoute, ApplicationsApi, AuthApi, type CreateApplicationInput, type CreateDatabaseInput, type CreateDatabaseResult, type CreateDomainInput, type CreateDomainResult, type CreateEmailInput, type CreateEmailResult, type CreateOnDeploy, type CreatedToken, DEFAULT_APP, DEFAULT_BAAS_URL, DEFAULT_CONSOLE_URL, type DatabaseSummary, DatabasesApi, type DeleteDatabaseResult, type DeleteEmailResult, type DeployKind, type DeployOptions, type DeployResult, type Domain, DomainsApi, EmailApi, type EmailSummary, LUMEN_BUILD, type LoginPrecheck, type LoginResult, type Privilege, 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, 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, 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

@@ -59,6 +59,9 @@ declare class RoxyonClient {
     private sessionToken?;
     private anon?;
     constructor(opts?: RoxyonClientOptions);
+    /** Same endpoints and app, no user credentials: for public reads (catalog, quotes)
+     * that must work for PAT callers too, whose token the BaaS does not accept. */
+    publicClient(): RoxyonClient;
     getSessionToken(): string | undefined;
     setSessionToken(token: string | undefined): void;
     /** Mint (or reuse) an anonymous access token from the public app credentials. */
@@ -364,6 +367,107 @@ declare class AuthApi {
     logout(): Promise<void>;
 }
 
+/** Billing cycles the checkout accepts (Pricing::CYCLE_MONTHS). */
+declare const BILLING_CYCLES: readonly ["monthly", "quarterly", "yearly", "biennial"];
+type BillingCycle = (typeof BILLING_CYCLES)[number];
+interface CatalogProduct {
+    /** Plan objectId: what quotes and orders take. */
+    planId: string;
+    /** Plan code, e.g. `SCALE-S`. */
+    sku: string;
+    name: string;
+    /** Service type, e.g. `cloud.vps.scale`, `cloud.hosting.solo`. */
+    category: string;
+    vcpu?: number;
+    ramGb?: number;
+    diskGb?: number;
+    cpuType?: string;
+    /** Dedicated IPv4 addresses included (servers). */
+    ipv4Included?: number;
+    /** List prices in USD before tax, per cycle. Quote for the buyer's currency and tax. */
+    pricesUSD: Partial<Record<BillingCycle, number>>;
+    /** Setup fee in USD per cycle, when not zero. */
+    setupFeeUSD?: Partial<Record<BillingCycle, number>>;
+    /** `out` = cannot be ordered right now. */
+    stock: 'in' | 'out';
+    /** Feature table as the console shows it. */
+    features?: Record<string, unknown>;
+}
+interface QuoteInput {
+    planId: string;
+    cycle: BillingCycle;
+    /** ISO 4217, e.g. `SAR`. Default USD. */
+    currency?: string;
+    /** ISO 3166 alpha-2, decides tax (e.g. `SA` = 15% VAT). Empty = no tax line. */
+    country?: string;
+}
+interface Quote {
+    planId: string;
+    cycle: string;
+    currency: string;
+    lineItems: Array<{
+        label: string;
+        amount: string;
+        amountUSD: string;
+    }>;
+    subtotal: string;
+    taxRate: string;
+    taxLabel: string;
+    taxAmount: string;
+    discountAmount: string;
+    total: string;
+    fxRate: string;
+    baseAmountUSD: string;
+}
+interface BillingSubscription {
+    id: string;
+    name: string;
+    status: string;
+    plan: string;
+    sku: string;
+    cycle: string;
+    price: string;
+    currency: string;
+    nextBillingDate: string | null;
+    autoRenew: boolean;
+    serverState: string | null;
+    publicIp: string | null;
+}
+interface Invoice {
+    id: string;
+    number: string;
+    type: string;
+    status: string;
+    total: string;
+    currency: string;
+    dueDate: string | null;
+    subscription: string | null;
+    createdAt: string;
+    payUrl: string | null;
+}
+/** Invoice statuses a customer can still pay. */
+declare const PAYABLE_STATUSES: readonly ["pending", "overdue", "failed"];
+declare function isPayable(status: string): boolean;
+/**
+ * Catalog + quotes (public, no sign-in) and the caller's own subscriptions + invoices
+ * (console, session or PAT). Read-only: nothing here creates orders or invoices.
+ */
+declare class BillingApi {
+    private readonly client;
+    private readonly pub;
+    constructor(client: RoxyonClient, pub?: RoxyonClient);
+    catalog(): Promise<CatalogProduct[]>;
+    /** What checkout would charge for a new subscription: the server's own pricing (GET /_payment/quote). */
+    quote(input: QuoteInput): Promise<Quote>;
+    /** The caller's own subscriptions (rows they own), newest first. */
+    subscriptions(): Promise<BillingSubscription[]>;
+    /** The caller's own invoices, newest first. */
+    invoices(opts?: {
+        status?: string;
+        limit?: number;
+    }): Promise<Invoice[]>;
+}
+
 interface CreateDatabaseInput {
     /** DB name suffix — the platform prefixes it with the subscription's own username (globally unique). */
     name: string;
@@ -586,6 +690,76 @@ declare class SubscriptionsApi {
     resolve(userId: string, preferred?: string): Promise<Subscription>;
 }
 
+/** BaaS V2 base. V1 (`/1`) is frozen; app data tools speak V2 only. */
+declare const DEFAULT_BAAS_V2_URL = "https://www.beaapis.com/2";
+/** V2 caps one page at 200 rows. */
+declare const BAAS_MAX_PAGE = 200;
+/** V2 takes 1 to 50 requests per batch. */
+declare const BAAS_MAX_BATCH = 50;
+interface BaasDataOptions {
+    /** The app's secret key (`rxsk_…`): server scope, from the project's API keys in Roxyon Base. */
+    secretKey: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+type BaasRow = Record<string, unknown>;
+interface BaasQuery {
+    /** e.g. `{ Status: 'active', Age: { gt: 18 } }`; `in` takes a comma-joined string. */
+    where?: Record<string, unknown>;
+    /** `*` and/or column names, comma separated. Defaults to `*`. */
+    fields?: string;
+    /** Comma list, `-` for descending, e.g. `-createdAt`. */
+    order?: string;
+    /** 1 to 200 (default 50). */
+    limit?: number;
+    skip?: number;
+    /** Also return the total number of matching rows. */
+    count?: boolean;
+}
+interface BaasBatchRequest {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** `/Class` or `/Class/<id>`. */
+    path: string;
+    body?: Record<string, unknown>;
+}
+/** One batch answer: `ok:false` with `error`/`message`, or that request's own V2 answer. */
+interface BaasBatchResult {
+    status: number;
+    ok?: boolean;
+    error?: string;
+    message?: string;
+    result?: BaasRow;
+    results?: BaasRow[];
+    count?: number;
+    id?: string;
+}
+/**
+ * Records of ONE app on BaaS V2, as that app's own backend (server scope, `X-RX-Secret-Key`).
+ * Server scope passes every class rule, so treat the key like a database password. V2 answers
+ * failures as `{ok:false, error, message}` with an HTTP status; every call throws on those.
+ * Schema changes are not reachable with a secret key (console API only).
+ */
+declare class BaasDataApi {
+    private readonly baseUrl;
+    private readonly secretKey;
+    private readonly _fetch;
+    constructor(opts: BaasDataOptions);
+    private call;
+    private static recordPath;
+    query(className: string, q?: BaasQuery): Promise<{
+        rows: BaasRow[];
+        count?: number;
+    }>;
+    get(className: string, objectId: string): Promise<BaasRow>;
+    /** Returns the created row as stored. */
+    create(className: string, data: BaasRow): Promise<BaasRow>;
+    update(className: string, objectId: string, data: BaasRow): Promise<BaasRow>;
+    /** The id goes in the URL path, never the body. */
+    delete(className: string, objectId: string): Promise<void>;
+    /** 1 to 50 record requests in one call; one failing doesn't stop the others. */
+    batch(requests: BaasBatchRequest[]): Promise<BaasBatchResult[]>;
+}
+
 /** Returns the error message from a BaaS response, or `''` when the call worked. */
 declare function rxError(r: unknown): string;
 declare class RoxyonApiError extends Error {
@@ -695,8 +869,9 @@ declare class Roxyon {
     readonly databases: DatabasesApi;
     readonly email: EmailApi;
     readonly ssh: SshApi;
+    readonly billing: BillingApi;
     constructor(options?: RoxyonClientOptions | RoxyonClient);
     get sessionToken(): string | undefined;
 }
 
-export { AccountApi, type AccountApp, type AccountContext, type AccountDomain, type AccountSubscription, type Application, type ApplicationProcess, type ApplicationRoute, ApplicationsApi, AuthApi, type CreateApplicationInput, type CreateDatabaseInput, type CreateDatabaseResult, type CreateDomainInput, type CreateDomainResult, type CreateEmailInput, type CreateEmailResult, type CreateOnDeploy, type CreatedToken, DEFAULT_APP, DEFAULT_BAAS_URL, DEFAULT_CONSOLE_URL, type DatabaseSummary, DatabasesApi, type DeleteDatabaseResult, type DeleteEmailResult, type DeployKind, type DeployOptions, type DeployResult, type Domain, DomainsApi, EmailApi, type EmailSummary, LUMEN_BUILD, type LoginPrecheck, type LoginResult, type Privilege, 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, 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, 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 };