@roxyon/api-client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,543 @@
+/**
+ * GET query serialisation for the BaaS, matching the `Obj2Par` helper in the
+ * browser SDK (`rx.js`): nested objects become PHP-style bracket keys
+ * (`where[User]=abc`, `where[Status][in]=a,b,c`).
+ *
+ * Two hard-won rules (see the `roxyon-api-write-failures` notes):
+ *  - The `in` operator takes a **comma-joined string, not an array**. An array
+ *    serialises to `where[X][in][0]=…` bracket notation the API does not read.
+ *    Pass `{ in: ['a', 'b'] }` here and we join it for you.
+ *  - A `select` subquery nested inside an `or` group crashes the API. Resolve
+ *    ids in a first query, then `or: [..., { objectId: { in: 'a,b' } }]`.
+ */
+type QueryValue = string | number | boolean | null | undefined | QueryValue[] | {
+    [k: string]: QueryValue;
+};
+type QueryObject = Record<string, QueryValue>;
+/** Serialise a query object to a `key=value&...` string (no leading `?`). */
+declare function toQueryString(query: QueryObject | undefined): string;
+
+interface RoxyonClientOptions {
+    /** BaaS application id. Defaults to the public console app. */
+    appId?: string;
+    /** Public JavaScript key, used to mint an anonymous token. */
+    javascriptKey?: string;
+    /** REST API key. Optional; grants full access — only for trusted server use. */
+    restKey?: string;
+    /** A user session token (from {@link AuthApi.login}). */
+    sessionToken?: string;
+    /** BaaS REST base, e.g. `https://www.beaapis.com/1`. */
+    baseUrl?: string;
+    /** Console base that serves the `/applications/*` endpoints. */
+    consoleUrl?: string;
+    /** Custom fetch (tests / proxies). */
+    fetch?: typeof fetch;
+}
+interface RequestOptions {
+    query?: QueryObject;
+    body?: unknown;
+    headers?: Record<string, string>;
+    /** Skip the Authorization/session header entirely (used for token minting). */
+    skipAuth?: boolean;
+    /** Send/parse the response even on a non-2xx status instead of throwing. */
+    tolerateHttpError?: boolean;
+    signal?: AbortSignal;
+}
+/**
+ * Low-level transport for the Roxyon BaaS and console app endpoints.
+ *
+ * Auth precedence per request: explicit `sessionToken` -> `restKey` ->
+ * a lazily-minted anonymous access token (public app credentials).
+ */
+declare class RoxyonClient {
+    readonly baseUrl: string;
+    readonly consoleUrl: string;
+    private readonly appId;
+    private readonly javascriptKey;
+    private readonly restKey?;
+    private readonly _fetch;
+    private sessionToken?;
+    private anon?;
+    constructor(opts?: RoxyonClientOptions);
+    getSessionToken(): string | undefined;
+    setSessionToken(token: string | undefined): void;
+    /** Mint (or reuse) an anonymous access token from the public app credentials. */
+    private anonToken;
+    /** A Personal Access Token (`roxp_…`) authenticates the console endpoints via
+     * `Authorization: Bearer`; it is not a BaaS session token. */
+    private get isPat();
+    private authHeaders;
+    /** A raw BaaS request. `path` is relative to {@link baseUrl} (leading `/`). */
+    request<T = unknown>(method: string, path: string, opts?: RequestOptions): Promise<T>;
+    /** A request against the console app endpoints ({@link consoleUrl}). */
+    console<T = unknown>(method: string, path: string, opts?: RequestOptions): Promise<T>;
+    private rawRequest;
+    get<T = unknown>(path: string, query?: QueryObject, opts?: RequestOptions): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, opts?: RequestOptions): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown, opts?: RequestOptions): Promise<T>;
+    del<T = unknown>(path: string, body?: unknown, opts?: RequestOptions): Promise<T>;
+}
+
+type TokenScope = 'deploy' | 'logs' | 'read';
+interface TokenSummary {
+    id: string;
+    name: string;
+    prefix: string;
+    scopes: TokenScope[];
+    lastUsedAt: string | null;
+    expiresAt: string | null;
+    createdAt: string;
+}
+interface CreatedToken {
+    /** The full `roxp_…` secret — shown once. Use it as `ROXYON_TOKEN`. */
+    token: string;
+    name: string;
+    scopes: TokenScope[];
+    expiresAt: string | null;
+}
+/**
+ * Personal Access Tokens — for the CLI in CI and for the MCP server running
+ * headless. Managed only while signed in with a session (`roxyon login`); a PAT
+ * cannot mint or revoke another PAT.
+ *
+ * `GET/POST/DELETE /account/tokens` — console endpoints.
+ */
+declare class TokensApi {
+    private readonly client;
+    constructor(client: RoxyonClient);
+    list(): Promise<TokenSummary[]>;
+    create(name: string, opts?: {
+        scopes?: TokenScope[];
+        expiresInDays?: number;
+    }): Promise<CreatedToken>;
+    revoke(id: string): Promise<void>;
+}
+
+interface AccountSubscription {
+    id: string;
+    name: string;
+    status: string;
+    node: string;
+    datacenter: string;
+    container: string;
+}
+interface AccountDomain {
+    id: string;
+    name: string;
+    subscription: string;
+}
+interface AccountContext {
+    user: {
+        id: string;
+        email: string;
+    };
+    scopes: (TokenScope | '*')[];
+    subscriptions: AccountSubscription[];
+    domains: AccountDomain[];
+}
+interface AccountApp {
+    id: string;
+    name: string;
+    status: string;
+    desiredState: string;
+    runtime: string;
+    configRevision: number;
+    appliedRevision: number;
+    lastError: string | null;
+    sourcePath: string;
+    repo: {
+        url: string;
+        branch: string;
+    } | null;
+}
+/**
+ * `GET /account/context` — one call the CLI / MCP server use to plan a deploy:
+ * the signed-in user, their subscriptions (with node), and their domains.
+ * Resolvable by a session token OR a Personal Access Token, so a CI job with
+ * only a PAT never has to touch the BaaS.
+ */
+declare class AccountApi {
+    private readonly client;
+    private cache?;
+    constructor(client: RoxyonClient);
+    context(opts?: {
+        fresh?: boolean;
+    }): Promise<AccountContext>;
+    private fetch;
+    /** `GET /account/apps` — the account's applications (list, PAT-safe). */
+    apps(): Promise<AccountApp[]>;
+    /** One application by id, PAT-safe (filters {@link apps}). */
+    getApp(id: string): Promise<AccountApp | undefined>;
+    /** Pick the subscription to deploy against — the preferred one, else the only/first. */
+    resolveSubscription(preferred?: string): Promise<AccountSubscription>;
+}
+
+interface Application {
+    objectId: string;
+    Name: string;
+    Status?: string;
+    DesiredState?: string;
+    SourcePath?: string;
+    Runtime?: string;
+    RuntimeVersion?: string;
+    Preset?: string;
+    ConfigRevision?: number;
+    AppliedRevision?: number;
+    LastError?: string;
+    Env?: string;
+    RepoUrl?: string;
+    Subscription?: string;
+    [k: string]: unknown;
+}
+interface ApplicationProcess {
+    objectId: string;
+    Application?: string;
+    Type?: string;
+    Command?: string;
+    Status?: string;
+    Port?: number;
+}
+interface ApplicationRoute {
+    objectId: string;
+    Application?: string;
+    Domain?: string;
+    Path?: string;
+    Enabled?: number | string;
+}
+interface DeployResult {
+    ok: boolean;
+    application: string;
+    created?: boolean;
+    configRevision?: number;
+    files?: number;
+    bytes?: number;
+    error?: string;
+}
+/** Params for creating an application on its first deploy (no id yet). */
+interface CreateOnDeploy {
+    host: string;
+    folder?: string;
+    runtime: 'node' | 'python' | 'php';
+    runtimeVersion?: string;
+    preset?: string;
+    command?: string;
+    public?: boolean;
+}
+interface CreateApplicationInput {
+    subscription: string;
+    name: string;
+    /** Absolute source path: `/home/www/<host>/public_html/<folder>`. */
+    sourcePath: string;
+    runtime: string;
+    runtimeVersion: string;
+    preset: string;
+    /** The web process start command. */
+    command: string;
+    /** Route host (`Domains.objectId`). */
+    domainId: string;
+    /** `.env`-style object stored as JSON on `Applications.Env`. */
+    env?: Record<string, string>;
+    /** Make the app public (route serves the app instead of the host's files). */
+    public?: boolean;
+}
+/**
+ * The Roxyon Applications system. Deployment is declarative: rows describe the
+ * desired state and every meaningful change bumps `ConfigRevision`; a
+ * server-side reconciler builds the source in an isolated release dir and
+ * (re)starts a systemd unit, writing back `Status` / `AppliedRevision` /
+ * `LastError`. Mirrors `applications.view` + `modals/app_form.view`.
+ */
+declare class ApplicationsApi {
+    private readonly client;
+    constructor(client: RoxyonClient);
+    list(subscriptionId: string): Promise<Application[]>;
+    get(id: string): Promise<Application | undefined>;
+    /** Create the application + its web process + a route, matching `createNew()`. */
+    create(input: CreateApplicationInput): Promise<{
+        application: string;
+        process: string;
+        route: string;
+    }>;
+    /** Read an application's environment. `GET /applications/env`. */
+    getEnv(applicationId: string): Promise<Record<string, string>>;
+    /**
+     * Merge `set` and delete `remove`, bumping `ConfigRevision`. `PORT`/`HOST` are
+     * ignored (platform-managed). `POST /applications/env`. Returns the new env.
+     */
+    setEnv(applicationId: string, changes: {
+        set?: Record<string, string>;
+        remove?: string[];
+    }): Promise<{
+        env: Record<string, string>;
+        changed: string[];
+        configRevision: number;
+    }>;
+    /** Rebuild from the latest source and restart. `POST /applications/action`. */
+    deploy(applicationId: string): Promise<void>;
+    /** Bounce the process only — no rebuild. `POST /applications/action`. */
+    restart(applicationId: string): Promise<void>;
+    /**
+     * Tail the app's journal. `POST /applications/logs` returns one block per
+     * process (`{ type, unit, output }`); this flattens them to lines, each
+     * prefixed with the process type when there is more than one.
+     */
+    logs(applicationId: string, lines?: number): Promise<string[]>;
+    /** Connect a git remote for push-to-deploy. `POST /applications/repo/connect`. */
+    repoConnect(applicationId: string, repoUrl: string, branch?: string): Promise<{
+        provider?: string;
+        deployKey?: string;
+        webhookUrl?: string;
+        secret?: string;
+        hint?: string;
+    }>;
+    /**
+     * Upload a gzipped tarball of the project source. The endpoint lands it in the
+     * application's `SourcePath` and bumps `ConfigRevision` (the reconciler then
+     * builds it in a release dir exactly as for a git deploy).
+     *
+     * `POST /applications/deploy` — NEW endpoint (see `backend/` in this repo).
+     */
+    uploadSource(target: string | CreateOnDeploy, tarball: Uint8Array): Promise<DeployResult>;
+}
+
+interface SessionGrant {
+    session_token: string;
+    refresh_token?: string;
+    expires_in?: number;
+    status?: string;
+}
+interface RoxyonUser {
+    objectId: string;
+    Email?: string;
+    Username?: string;
+    Name?: string;
+    Currency?: string;
+    Language?: string;
+    [k: string]: unknown;
+}
+interface LoginPrecheck {
+    ok?: boolean;
+    error?: string;
+    stepUpRequired?: boolean;
+    challengeId?: string;
+}
+interface LoginResult {
+    sessionToken: string;
+    refreshToken?: string;
+    expiresIn?: number;
+    /** True when an OTP code is still required — call {@link AuthApi.verifyOtp}. */
+    stepUpRequired?: boolean;
+    challengeId?: string;
+}
+/**
+ * Wraps the console's login flow:
+ *   1. `POST /_account/login-precheck` — validates credentials, decides whether
+ *      an OTP step-up is required, and (when it is) returns a `challengeId`.
+ *   2a. no step-up -> `POST /Auth/login` finalises and returns a session token.
+ *   2b. step-up    -> caller collects the code, then `POST /Auth/login/otp-verify`.
+ *
+ * Mirrors `signin.view` / `otp.view` in `console.roxyon.com`.
+ */
+declare class AuthApi {
+    private readonly client;
+    constructor(client: RoxyonClient);
+    /**
+     * Best-effort device/step-up precheck. `/_account/login-precheck` is a console
+     * cloud function that may be gated behind the REST key (not reachable from a
+     * public client) — in that case this resolves to `{}` and login falls back to
+     * `/Auth/login`, which is itself the security boundary and re-checks the
+     * device. Only a definitive `{ ok: false }` / `stepUpRequired` is acted on.
+     */
+    precheck(email: string, password: string, metadata?: Record<string, string>): Promise<LoginPrecheck>;
+    /**
+     * Full login. Returns a session token on success, or `stepUpRequired` with a
+     * `challengeId` when an OTP code is needed next.
+     */
+    login(email: string, password: string, metadata?: Record<string, string>): Promise<LoginResult>;
+    /** Complete an OTP step-up with the code the user received. */
+    verifyOtp(challengeId: string, code: string): Promise<LoginResult>;
+    /** Start an OTP-only sign-in (no password). Returns a `challengeId`. */
+    startOtp(email: string): Promise<{
+        challengeId: string;
+    }>;
+    /** The currently authenticated user. Requires a session token on the client. */
+    me(): Promise<RoxyonUser>;
+    logout(): Promise<void>;
+}
+
+interface Domain {
+    objectId: string;
+    Name: string;
+}
+/** Domains (hosts) attached to a subscription — used to place an application. */
+declare class DomainsApi {
+    private readonly client;
+    constructor(client: RoxyonClient);
+    list(subscriptionId: string): Promise<Domain[]>;
+}
+
+interface StaticDeployResult {
+    ok: boolean;
+    host: string;
+    path: string;
+    files?: number;
+    error?: string;
+}
+/**
+ * Static-site deploy: upload built files (a LumenJS `--serverless` build, or any
+ * static output) into a host's document root
+ * (`/home/www/<host>/public_html[/<folder>]`), served directly by nginx. No
+ * Application row, no process.
+ *
+ * `POST /sites/deploy` — NEW endpoint (see `backend/` in this repo).
+ */
+declare class SitesApi {
+    private readonly client;
+    constructor(client: RoxyonClient);
+    deploy(host: string, folder: string, tarball: Uint8Array): Promise<StaticDeployResult>;
+}
+
+interface Subscription {
+    objectId: string;
+    Name?: string;
+    Status?: string;
+    Username?: string;
+    /** Infra node the subscription's container lives on (internal). */
+    Node?: string;
+    Datacenter?: string;
+    [k: string]: unknown;
+}
+interface Privilege {
+    objectId: string;
+    Type?: string;
+    Subscription?: string;
+    _Subscription?: {
+        results: Subscription[];
+    };
+    [k: string]: unknown;
+}
+/** Access to the caller's subscriptions (via their Privileges rows). */
+declare class SubscriptionsApi {
+    private readonly client;
+    constructor(client: RoxyonClient);
+    /** All subscriptions the signed-in user has a Privilege on. */
+    list(userId: string): Promise<Subscription[]>;
+    /**
+     * Resolve the subscription to act on. Prefers an exact `objectId` or `Name`
+     * match against `preferred`; otherwise the first active subscription; otherwise
+     * the first one. Throws when the account has none.
+     */
+    resolve(userId: string, preferred?: string): Promise<Subscription>;
+}
+
+/** Returns the error message from a BaaS response, or `''` when the call worked. */
+declare function rxError(r: unknown): string;
+declare class RoxyonApiError extends Error {
+    readonly code?: number;
+    readonly type?: string;
+    readonly status?: number;
+    readonly body: unknown;
+    constructor(message: string, opts?: {
+        code?: number;
+        type?: string;
+        status?: number;
+        body?: unknown;
+    });
+}
+/** True when an error looks like "the session/token is gone", so the caller can re-auth. */
+declare function isAuthError(err: unknown): boolean;
+/** Throw a {@link RoxyonApiError} if `r` carries a BaaS error; otherwise return it typed. */
+declare function assertOk<T>(r: T): T;
+
+/**
+ * `.env`-style block <-> JSON object, ported verbatim from `appfEnvParse` /
+ * `appfEnvToLines` in `console.roxyon.com/.../modals/app_form.view` so the CLI
+ * and the console form agree byte-for-byte on what `Applications.Env` holds.
+ *
+ * The server re-sanitises again (`ApplicationRenderer::envPair`), so this only
+ * needs to be reasonable. `PORT` and `HOST` are set by the platform — callers
+ * should not write them.
+ */
+declare function parseEnv(text: string): Record<string, string>;
+declare function formatEnv(obj: Record<string, string> | null | undefined): string;
+/** Parse the JSON string stored on `Applications.Env`. */
+declare function envFromStored(jsonStr: string | undefined): Record<string, string>;
+
+/**
+ * Runtime / version / framework catalog — a verbatim copy of the `RUNTIMES`
+ * table in `console.roxyon.com/.../modals/app_form.view`. These are the versions
+ * actually installed in the Cloud Hosting containers; offering an uninstalled
+ * one produces a deploy that fails at build time for a reason the user cannot
+ * act on.
+ *
+ * TODO(M4): the console form and this file should both import one shared JSON
+ * published at `roxyon.com/runtimes.json` so they never drift.
+ */
+type RuntimeName = 'lumen' | 'node' | 'python' | 'php';
+interface RuntimeSpec {
+    versions: string[];
+    defaultVersion: string;
+    presets: Array<[value: string, label: string]>;
+    command: string;
+}
+declare const RUNTIMES: Record<Exclude<RuntimeName, 'lumen'>, RuntimeSpec>;
+/**
+ * A LumenJS project (`runtime: "lumen"`) builds to static files with
+ * `lm build --serverless` and is served straight from the host's document root
+ * by nginx — no long-running process, no systemd unit, no Application row. It
+ * deploys through the "static" path (upload the built `dist/` to
+ * `/home/www/<host>/public_html[/<folder>]`).
+ *
+ * Node / Python / PHP projects deploy through the "app" path (the Applications
+ * system: upload source, bump ConfigRevision, reconciler builds + runs it).
+ */
+type DeployKind = 'static' | 'app';
+declare const LUMEN_BUILD: {
+    readonly command: "lm build --serverless";
+    /** Directory `lm build --serverless` writes to, relative to the project root. */
+    readonly outDir: "dist";
+};
+
+/**
+ * Default endpoints and the public application credentials the client uses to
+ * mint an anonymous token before a user logs in.
+ *
+ * `X-BEA-JavaScript-Key` is a **public** key (it ships in browser bundles by
+ * design — see `console.roxyon.com/src/index.js`). It is safe to embed here.
+ * The REST key is never embedded — user actions always run under a session
+ * token or a Personal Access Token.
+ *
+ * TODO(M1): provision a dedicated `roxyon-cli` BaaS application and swap these
+ * for its App-ID / JavaScript-Key so CLI traffic is attributable and rate-limited
+ * separately from the web console. Until then the client reuses the console's
+ * public pair, which is already exposed in shipped frontend code.
+ */
+declare const DEFAULT_BAAS_URL = "https://www.beaapis.com/1";
+declare const DEFAULT_CONSOLE_URL = "https://console.roxyon.com";
+declare const DEFAULT_APP: {
+    readonly appId: "jAtp2zHGU3FbnrQWrToALFakd_vbiY0ywihn4Hj54lw";
+    readonly javascriptKey: "w2Y9USRg0COtNe-fUqOaC1OOOlNCnV2BG8GZF80w4x8";
+};
+
+/**
+ * Convenience facade bundling every sub-API over one {@link RoxyonClient}.
+ *
+ * ```ts
+ * const roxyon = new Roxyon({ sessionToken });          // or a roxp_ PAT
+ * const ctx = await roxyon.account.context();           // user + subs + domains
+ * ```
+ */
+declare class Roxyon {
+    readonly client: RoxyonClient;
+    readonly auth: AuthApi;
+    readonly account: AccountApi;
+    readonly tokens: TokensApi;
+    readonly subscriptions: SubscriptionsApi;
+    readonly domains: DomainsApi;
+    readonly applications: ApplicationsApi;
+    readonly sites: SitesApi;
+    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 CreateOnDeploy, type CreatedToken, DEFAULT_APP, DEFAULT_BAAS_URL, DEFAULT_CONSOLE_URL, type DeployKind, type DeployResult, type Domain, DomainsApi, LUMEN_BUILD, type LoginPrecheck, type LoginResult, type Privilege, RUNTIMES, type RequestOptions, Roxyon, RoxyonApiError, RoxyonClient, type RoxyonClientOptions, type RoxyonUser, type RuntimeName, type RuntimeSpec, type SessionGrant, SitesApi, type StaticDeployResult, type Subscription, SubscriptionsApi, type TokenScope, type TokenSummary, TokensApi, assertOk, envFromStored, formatEnv, isAuthError, parseEnv, rxError, toQueryString };