@kryshtop/bstack 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Open Source Contributors
+
+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,324 @@
+# bstack
+
+BrowserStack App Automate SDK and CLI for uploads, builds, sessions, and media workflows.
+
+[![Build](https://github.com/kryshtop/bstack/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/kryshtop/bstack/actions/workflows/build.yml)
+[![Tests](https://github.com/kryshtop/bstack/actions/workflows/unit-tests.yml/badge.svg?branch=main)](https://github.com/kryshtop/bstack/actions/workflows/unit-tests.yml)
+[![Version](https://img.shields.io/badge/version-1.0.0-blue?style=flat-square)](https://github.com/kryshtop/bstack/blob/main/package.json)
+[![GitHub Stars](https://img.shields.io/badge/stars-view%20on%20GitHub-181717?style=flat-square&logo=github)](https://github.com/kryshtop/bstack/stargazers)
+[![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](https://github.com/kryshtop/bstack/blob/main/LICENSE)
+
+`@kryshtop/bstack` is a CLI-first BrowserStack App Automate package that ships both:
+
+- a CLI binary: `bstack`
+- a TypeScript/JavaScript SDK for registry-driven BrowserStack App Automate API access
+
+It is designed for local operator workflows and CI scripting. In most cases you should install it globally, or as a project-local `devDependency` when you want a pinned CLI version inside a repository. The package also exposes an SDK surface for advanced programmatic use, but it is primarily intended as an operator utility rather than a runtime dependency of application packages.
+
+## Features
+
+- Interactive terminal UI for common BrowserStack App Automate workflows
+- Scriptable command mode for CI and shell automation
+- SDK exports for HTTP client, registry, services, normalizers, and types
+- Local credential persistence with OS keychain preference
+
+## Requirements
+
+- Node.js `>=22.20.0`
+- npm `>=10`
+
+## Installation
+
+### Recommended: global CLI usage
+
+```bash
+npm install -g @kryshtop/bstack
+bstack --help
+```
+
+### Project-local CLI usage
+
+```bash
+npm install -D @kryshtop/bstack
+npx bstack --help
+```
+
+### From a local tarball
+
+```bash
+npm pack
+npm install -D ./kryshtop-bstack-1.0.0.tgz
+```
+
+## Quick Start
+
+### CLI
+
+```bash
+bstack auth login
+bstack auth status
+bstack appium apps list
+```
+
+If installed locally instead of globally:
+
+```bash
+npx @kryshtop/bstack --help
+```
+
+### SDK
+
+If you intentionally want to use the package programmatically, install it in the way that matches your project policy. For CLI-only use, prefer the global or `devDependency` installs above.
+
+```ts
+import {
+  BrowserStackHttpClient,
+  EndpointRegistry,
+  ResourceService,
+  endpointDefinitions,
+} from '@kryshtop/bstack';
+
+const registry = new EndpointRegistry(endpointDefinitions);
+const http = new BrowserStackHttpClient({
+  username: process.env.BSTACK_USERNAME!,
+  accessKey: process.env.BSTACK_ACCESS_KEY!,
+  storageStrategy: 'plain-file',
+  createdAt: new Date().toISOString(),
+  updatedAt: new Date().toISOString(),
+});
+
+const service = new ResourceService(registry, http);
+const builds = await service.listBuilds('appium');
+console.log(builds);
+```
+
+## CLI Usage
+
+### Interactive mode
+
+Run with no subcommand:
+
+```bash
+bstack
+```
+
+or explicitly:
+
+```bash
+bstack menu
+```
+
+### Command mode
+
+Global options:
+
+- `--json`
+- `--debug-http`
+- `--verbose`
+- `--master-key <key>`
+- `--allow-plain-storage`
+- `--base-url <url>`
+
+Examples:
+
+```bash
+bstack auth login
+bstack auth validate
+bstack auth status --json
+bstack appium apps upload ./MyApp.apk --custom-id SampleApp
+bstack appium builds list --status running
+bstack maestro suites upload ./maestro-suite.zip
+bstack xcuitest sessions get <sessionId> --build <buildId>
+bstack media upload ./fixtures/profile.png
+bstack explorer
+```
+
+## SDK Exports
+
+The package root exports:
+
+- `AuthService`
+- `BrowserStackHttpClient`
+- `BrowserStackApiError`
+- `buildMultipartPayload`
+- `EndpointRegistry`
+- `endpointDefinitions`
+- `ResourceService`
+- `frameworkDescriptors`
+- `getFrameworkDescriptor`
+- `validateUploadPath`
+- `CommandRuntime`
+- `createProgram`
+- `runCli`
+- config path helpers
+- normalizers
+- public domain types
+
+Internal implementation files are not exported through the package root.
+
+## Authentication
+
+The CLI uses BrowserStack username and access key.
+
+Supported sources:
+
+- interactive prompt
+- explicit CLI flags
+- environment variables you provide in your shell or CI
+
+### Login examples
+
+Interactive:
+
+```bash
+bstack auth login
+```
+
+Non-interactive:
+
+```bash
+bstack auth login --username "$BSTACK_USERNAME" --access-key "$BSTACK_ACCESS_KEY"
+```
+
+Encrypted local storage:
+
+```bash
+export BSTACK_MASTER_KEY='choose-a-strong-local-master-key'
+bstack auth login \
+  --username "$BSTACK_USERNAME" \
+  --access-key "$BSTACK_ACCESS_KEY" \
+  --storage encrypted-file
+```
+
+Plain-text storage is explicit only:
+
+```bash
+bstack auth login \
+  --username "$BSTACK_USERNAME" \
+  --access-key "$BSTACK_ACCESS_KEY" \
+  --storage plain-file \
+  --allow-plain-storage
+```
+
+## Environment Variables
+
+See [.env.example](./.env.example).
+
+Supported variables:
+
+- `BSTACK_USERNAME`
+- `BSTACK_ACCESS_KEY`
+- `BSTACK_MASTER_KEY`
+- `BSTACK_BASE_URL`
+- `BSTACK_HTTP_TIMEOUT_MS`
+
+## Credential and Session Storage
+
+Credentials are stored outside the repository root.
+
+Storage order for `--storage auto`:
+
+1. OS keychain via optional `keytar`
+2. encrypted file using your master key
+3. plain-text file only if you explicitly allow it
+
+Typical user config locations:
+
+- macOS: `~/Library/Application Support/bstack`
+- Linux: `~/.config/bstack`
+
+Persisted files may include:
+
+- `config.json`
+- `session.enc`
+- `session.json`
+- `last-response.json`
+
+Secrets are not bundled into the npm package.
+
+## Framework Coverage
+
+### Appium
+
+- apps: upload, list, group list, delete
+- builds: list, get
+- sessions: list, get, update status
+- plan and usage validation
+
+### Maestro
+
+- apps: upload, list, get, delete
+- test suites: upload, list, get, delete
+- builds: run, list, get, stop
+- sessions: get
+
+### Espresso
+
+- apps: upload, list, get, delete
+- test suites: upload, list, get, delete
+- builds: run, list, get, stop
+- sessions: get
+
+### Flutter Android
+
+- apps: upload, list, get, delete
+- test suites: upload, list, get, delete
+- builds: run, list, get, stop
+- sessions: get
+
+### Flutter iOS
+
+- test packages: upload, list, get, delete
+- builds: run, list, get, stop
+- sessions: get
+
+### Detox Android
+
+- apps: upload
+- app-client: upload
+- sessions: get
+
+### XCUITest
+
+- apps: upload, list, get, delete
+- test suites: upload, list, get, delete
+- builds: run, list, get, stop
+- sessions: get
+
+### Media
+
+- upload, list, group list, delete
+
+## Media Notes
+
+Media uploads return BrowserStack `media_url` values that you can plug into framework-specific execution payloads or capabilities.
+
+The package preserves raw BrowserStack responses instead of forcing a guessed capability abstraction.
+
+## Troubleshooting
+
+### No saved session found
+
+```bash
+bstack auth login
+```
+
+### Keychain support unavailable
+
+Use encrypted-file storage with a master key:
+
+```bash
+bstack auth login --storage encrypted-file --master-key '<key>'
+```
+
+### Encrypted session cannot be decrypted
+
+Set the same `BSTACK_MASTER_KEY` used when the session was created, or log in again and choose another storage backend.
+
+### Unsupported operation
+
+The requested command may not be available for that framework. Check `bstack help-frameworks` to see the currently supported operations.
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=kryshtop/bstack&type=Date)](https://www.star-history.com/#kryshtop/bstack&Date)

package/dist/api/http/BrowserStackHttpClient.d.ts

@@ -0,0 +1,30 @@
+import { type Method } from 'axios';
+import type { StoredSession } from '../../types/domain.js';
+import type { MultipartInput } from './multipart.js';
+export interface HttpClientOptions {
+    baseUrl?: string;
+    timeoutMs?: number;
+    retryAttempts?: number;
+    debugHttp?: boolean;
+}
+export interface RequestOptions {
+    method: Method;
+    path: string;
+    query?: Record<string, unknown>;
+    data?: unknown;
+    headers?: Record<string, string>;
+}
+export declare class BrowserStackHttpClient {
+    private readonly session;
+    private readonly options;
+    private readonly client;
+    private readonly timeoutMs;
+    private readonly retryAttempts;
+    constructor(session: StoredSession, options?: HttpClientOptions);
+    getAuthHeader(): string;
+    requestRaw<T = unknown>(options: RequestOptions): Promise<T>;
+    requestJson<T = unknown>(options: RequestOptions): Promise<T>;
+    uploadMultipart<T = unknown>(path: string, input: MultipartInput, fields?: Record<string, unknown>): Promise<T>;
+    private performRequest;
+    private buildPath;
+}

package/dist/api/http/BrowserStackHttpClient.js

@@ -0,0 +1,111 @@
+import axios from 'axios';
+import { DEFAULT_BASE_URL, DEFAULT_HTTP_TIMEOUT_MS, DEFAULT_RETRY_ATTEMPTS, } from '../../utils/constants.js';
+import { buildQuery } from '../../utils/query.js';
+import { BrowserStackApiError, isRetryableStatus, mapAxiosError } from './errors.js';
+import { buildMultipartPayload } from './multipart.js';
+export class BrowserStackHttpClient {
+    session;
+    options;
+    client;
+    timeoutMs;
+    retryAttempts;
+    constructor(session, options = {}) {
+        this.session = session;
+        this.options = options;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS;
+        this.retryAttempts = options.retryAttempts ?? DEFAULT_RETRY_ATTEMPTS;
+        this.client = axios.create({
+            baseURL: options.baseUrl ?? process.env.BSTACK_BASE_URL ?? DEFAULT_BASE_URL,
+            timeout: this.timeoutMs,
+            auth: {
+                username: session.username,
+                password: session.accessKey,
+            },
+            validateStatus: (status) => status >= 200 && status < 300,
+        });
+    }
+    getAuthHeader() {
+        return `Basic ${Buffer.from(`${this.session.username}:${this.session.accessKey}`).toString('base64')}`;
+    }
+    async requestRaw(options) {
+        return this.performRequest({
+            method: options.method,
+            url: this.buildPath(options.path, options.query),
+            data: options.data,
+            headers: options.headers,
+        });
+    }
+    async requestJson(options) {
+        return this.requestRaw(options);
+    }
+    async uploadMultipart(path, input, fields) {
+        const { form, headers } = await buildMultipartPayload({
+            ...input,
+            fields: normalizeFormFields(fields),
+        });
+        return this.performRequest({
+            method: 'POST',
+            url: path,
+            data: form,
+            headers,
+            maxContentLength: Infinity,
+            maxBodyLength: Infinity,
+        });
+    }
+    async performRequest(config) {
+        let attempt = 0;
+        while (true) {
+            try {
+                if (this.options.debugHttp) {
+                    const method = String(config.method ?? 'GET').toUpperCase();
+                    process.stderr.write(`[http] ${method} ${config.url}\n`);
+                }
+                const response = await this.client.request(config);
+                return response.data;
+            }
+            catch (error) {
+                attempt += 1;
+                if (axios.isAxiosError(error)) {
+                    const mapped = mapAxiosError(error);
+                    if (attempt < this.retryAttempts && mapped.retryable) {
+                        await sleep(backoffMs(attempt, mapped.statusCode));
+                        continue;
+                    }
+                    throw mapped;
+                }
+                const fallback = new BrowserStackApiError({
+                    code: 'UNKNOWN_HTTP_ERROR',
+                    message: error instanceof Error ? error.message : 'Unknown HTTP error',
+                    retryable: false,
+                });
+                if (attempt < this.retryAttempts && isRetryableStatus(fallback.statusCode)) {
+                    await sleep(backoffMs(attempt, fallback.statusCode));
+                    continue;
+                }
+                throw fallback;
+            }
+        }
+    }
+    buildPath(path, query) {
+        const params = buildQuery(query ?? {});
+        const queryString = params.toString();
+        return queryString ? `${path}?${queryString}` : path;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function backoffMs(attempt, statusCode) {
+    const base = statusCode === 429 ? 1_500 : 700;
+    return base * 2 ** (attempt - 1);
+}
+function normalizeFormFields(input) {
+    const normalized = {};
+    for (const [key, value] of Object.entries(input ?? {})) {
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            normalized[key] = value;
+        }
+    }
+    return normalized;
+}
+//# sourceMappingURL=BrowserStackHttpClient.js.map

package/dist/api/http/BrowserStackHttpClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserStackHttpClient.js","sourceRoot":"","sources":["../../../src/api/http/BrowserStackHttpClient.ts"],"names":[],"mappings":"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"}

package/dist/api/http/errors.d.ts

@@ -0,0 +1,11 @@
+import type { AxiosError } from 'axios';
+import type { ApiErrorShape } from '../../types/domain.js';
+export declare class BrowserStackApiError extends Error {
+    readonly statusCode?: number;
+    readonly code: string;
+    readonly details?: unknown;
+    readonly retryable: boolean;
+    constructor(shape: ApiErrorShape);
+}
+export declare function isRetryableStatus(statusCode?: number): boolean;
+export declare function mapAxiosError(error: AxiosError): BrowserStackApiError;

package/dist/api/http/errors.js

@@ -0,0 +1,31 @@
+export class BrowserStackApiError extends Error {
+    statusCode;
+    code;
+    details;
+    retryable;
+    constructor(shape) {
+        super(shape.message);
+        this.name = 'BrowserStackApiError';
+        this.statusCode = shape.statusCode;
+        this.code = shape.code;
+        this.details = shape.details;
+        this.retryable = shape.retryable;
+    }
+}
+export function isRetryableStatus(statusCode) {
+    return statusCode === 429 || Boolean(statusCode && statusCode >= 500);
+}
+export function mapAxiosError(error) {
+    const statusCode = error.response?.status;
+    const message = typeof error.response?.data === 'string'
+        ? error.response.data
+        : error.message || 'BrowserStack API request failed.';
+    return new BrowserStackApiError({
+        statusCode,
+        code: error.code ?? 'HTTP_ERROR',
+        message,
+        details: error.response?.data,
+        retryable: isRetryableStatus(statusCode) || error.code === 'ECONNABORTED',
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/api/http/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/api/http/errors.ts"],"names":[],"mappings":"AAIA,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7B,UAAU,CAAU;IACpB,IAAI,CAAS;IACb,OAAO,CAAW;IAClB,SAAS,CAAU;IAEnC,YAAmB,KAAoB;QACrC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;IACnC,CAAC;CACF;AAED,MAAM,UAAU,iBAAiB,CAAC,UAAmB;IACnD,OAAO,UAAU,KAAK,GAAG,IAAI,OAAO,CAAC,UAAU,IAAI,UAAU,IAAI,GAAG,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAiB;IAC7C,MAAM,UAAU,GAAG,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1C,MAAM,OAAO,GACX,OAAO,KAAK,CAAC,QAAQ,EAAE,IAAI,KAAK,QAAQ;QACtC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI;QACrB,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,kCAAkC,CAAC;IAE1D,OAAO,IAAI,oBAAoB,CAAC;QAC9B,UAAU;QACV,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,YAAY;QAChC,OAAO;QACP,OAAO,EAAE,KAAK,CAAC,QAAQ,EAAE,IAAI;QAC7B,SAAS,EAAE,iBAAiB,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc;KAC1E,CAAC,CAAC;AACL,CAAC"}

package/dist/api/http/multipart.d.ts

@@ -0,0 +1,13 @@
+import FormData from 'form-data';
+export interface MultipartInput {
+    filePath?: string;
+    fileFieldName?: string;
+    fileName?: string;
+    url?: string;
+    urlFieldName?: string;
+    fields?: Record<string, string | number | boolean | undefined>;
+}
+export declare function buildMultipartPayload(input: MultipartInput): Promise<{
+    form: FormData;
+    headers: Record<string, string>;
+}>;

package/dist/api/http/multipart.js

@@ -0,0 +1,28 @@
+import { createReadStream } from 'node:fs';
+import FormData from 'form-data';
+import mime from 'mime-types';
+import { assertReadableFile } from '../../utils/files.js';
+export async function buildMultipartPayload(input) {
+    const form = new FormData();
+    if (input.filePath) {
+        await assertReadableFile(input.filePath);
+        form.append(input.fileFieldName ?? 'file', createReadStream(input.filePath), {
+            contentType: mime.lookup(input.filePath) || 'application/octet-stream',
+            filename: input.fileName,
+        });
+    }
+    if (input.url) {
+        form.append(input.urlFieldName ?? 'url', input.url);
+    }
+    for (const [key, value] of Object.entries(input.fields ?? {})) {
+        if (value === undefined) {
+            continue;
+        }
+        form.append(key, String(value));
+    }
+    return {
+        form,
+        headers: form.getHeaders(),
+    };
+}
+//# sourceMappingURL=multipart.js.map

package/dist/api/http/multipart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multipart.js","sourceRoot":"","sources":["../../../src/api/http/multipart.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,QAAQ,MAAM,WAAW,CAAC;AACjC,OAAO,IAAI,MAAM,YAAY,CAAC;AAE9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAW1D,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,KAAqB;IAErB,MAAM,IAAI,GAAG,IAAI,QAAQ,EAAE,CAAC;IAE5B,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACnB,MAAM,kBAAkB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACzC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,IAAI,MAAM,EAAE,gBAAgB,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE;YAC3E,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,0BAA0B;YACtE,QAAQ,EAAE,KAAK,CAAC,QAAQ;SACzB,CAAC,CAAC;IACL,CAAC;IAED,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC;QACd,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,IAAI,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IACtD,CAAC;IAED,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;QAC9D,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAClC,CAAC;IAED,OAAO;QACL,IAAI;QACJ,OAAO,EAAE,IAAI,CAAC,UAAU,EAA4B;KACrD,CAAC;AACJ,CAAC"}

package/dist/api/normalizers/common.d.ts

@@ -0,0 +1,7 @@
+import type { BuildSummary, SessionSummary, UploadedArtifact } from '../../types/domain.js';
+export declare function normalizeArtifact(input: unknown): UploadedArtifact;
+export declare function normalizeBuildSummary(input: unknown): BuildSummary;
+export declare function normalizeSessionSummary(input: unknown): SessionSummary;
+export declare function normalizeArtifactCollection(input: unknown): UploadedArtifact[];
+export declare function normalizeBuildCollection(input: unknown): BuildSummary[];
+export declare function normalizeSessionCollection(input: unknown): SessionSummary[];