npm package: @lexoraxiom/appscreenz-sdk
Description: AppScreenz local SDK: browser capture helpers, Node screenshot output writer, and sync CLI.
Latest version: 0.0.2

# @lexoraxiom/appscreenz-sdk

Browser helpers (TypeScript), a Node API to write screenshots for sync, and the `appscreenz` CLI.

## Install

```bash
npm install @lexoraxiom/appscreenz-sdk
```

Published installs include built output under `dist/node/` for `@lexoraxiom/appscreenz-sdk/node` (no post-install build). If you depend on a **git checkout** of this repo, run `pnpm run build` in `packages/sdk` first.

## Imports

- **`@lexoraxiom/appscreenz-sdk`** — browser-only APIs, shipped as TypeScript. Use from a bundler (e.g. Vite, Next.js) with your usual TS setup. Not intended for plain Node without a TS loader.
- **`@lexoraxiom/appscreenz-sdk/node`** — compiled ESM + types. Use from Node to write PNGs and `manifest.json` where the CLI expects them.

```ts
import { writeScreenshotsToAppscreenzOutput } from '@lexoraxiom/appscreenz-sdk/node';

await writeScreenshotsToAppscreenzOutput({
  clean: true,
  screenshots: [
    {
      fileName: 'home-ios.png',
      data: pngBuffer,
      id: 'home',
      label: 'Home',
      platform: 'ios',
    },
  ],
});
```

Defaults: `rootDir` is `process.cwd()`; output goes to `.appscreenz/screenshots` under that root. With `clean: true`, existing `*.png` and `manifest.json` in that folder are removed first.

You can also generate those PNGs with the CLI (see below) or call `runGenerateScreenshots` from `@lexoraxiom/appscreenz-sdk/node` (same manifest format as `writeScreenshotsToAppscreenzOutput`).

## CLI: init, generate, connect, sync

### Local only (no Firebase)

From your **project root**, with the app **already running** at a known URL:

```bash
npm install -D @lexoraxiom/appscreenz-sdk
npx playwright install chromium
npx appscreenz init --url http://localhost:8081 --route / --route /paywall
npx appscreenz generate
```

- **`init`** creates `.appscreenz/project.json` and `.appscreenz/screenshots/` (no manual folders). Requires `--url` and at least one `--route`. Use `--force` to overwrite an existing config.
- **`generate`** uses Playwright (Chromium) with fixed **iPhone** and **Android** viewports, full-page PNGs per route, and writes PNGs + `manifest.json` under the configured screenshots directory. **`generate` does not use Firebase.**

### Optional: AppScreenz sync

After local screenshots exist, link the folder to a dashboard project and upload:

```bash
npx appscreenz connect --project <projectId>
npx appscreenz sync
npx appscreenz status
```

If you already ran **`init`** (or edited `project.json`), **`connect` merges** into that file: it keeps **`baseUrl`** and **`routes`** unless you pass **`--url`** or **`--route`** on `connect` to override or add paths.

### Firebase configuration (`connect`, `sync`, and remote `status` only)

The CLI talks to **your AppScreenz Firebase project** (Firestore + Storage). Add a `.env`, `.env.local`, or `apps/web/.env.local` (searched upward) containing:

| Variable | Purpose |
|----------|---------|
| `NEXT_PUBLIC_FIREBASE_API_KEY` | |
| `NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN` | |
| `NEXT_PUBLIC_FIREBASE_PROJECT_ID` | |
| `NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET` | |
| `NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID` | |
| `NEXT_PUBLIC_FIREBASE_APP_ID` | |
| `NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID` | Optional |
| `NEXT_PUBLIC_APPSCREENZ_ACCOUNT_ID` | Optional; defaults to a demo id if omitted |

Use `appscreenz connect --env /path/to/.env` when the file is not in a default location.

### Web vs native (`generate`)

`generate` runs **Playwright Chromium** against **HTTP(S) URLs**. It captures **web** pages (e.g. Next.js, Vite, **Expo web**). It does **not** capture native iOS/Android UI. For those, write PNGs with `writeScreenshotsToAppscreenzOutput`, then `appscreenz sync` if needed.

Use `--dir` on **`init`**, **`connect`**, or **`sync`** if screenshots should live somewhere other than `.appscreenz/screenshots`.

### `networkidle` and SPAs

`generate` waits for `networkidle` after each navigation. Apps with long-lived connections (polling, WebSockets) may never reach idle on some routes; use simple, public routes for best results.

## Config files

- `.appscreenz/project.json` — `screenshotsDir`, `baseUrl`, `routes[]`, optional `projectId` / `sourceId` / `accountId` after **`connect`**, plus sync metadata when applicable.
- `.appscreenz/screenshots/` — PNGs and `manifest.json` from **`generate`** or `writeScreenshotsToAppscreenzOutput`

### Node API reference

| Export | Purpose |
|--------|---------|
| `writeScreenshotsToAppscreenzOutput(options)` | Creates the folder, optionally cleans, writes PNGs + `manifest.json` |
| `runGenerateScreenshots(options)` | Playwright full-page capture per route × mobile preset; writes the same folder layout as above |
| `isLinkedToSaaS`, `mergeRoutes`, `normalizeBaseUrl`, `normalizeRoutePath`, `mergeGenerateConfigIntoProject`, `resolveScreenshotsRelativeDir`, `routePathToSlug` | Helpers for `.appscreenz/project.json` |
| `MOBILE_VIEWPORT_PRESETS` | Fixed `iphone` / `android` viewport sizes used by `runGenerateScreenshots` |
| `assertScreenshotBasenamePng(fileName)` | Validates a safe basename (no paths or `..`) |
| `DEFAULT_APPSCREENZ_SCREENSHOTS_RELATIVE_PATH` | `'.appscreenz/screenshots'` |

Each screenshot item: **`fileName`** (basename, `.png`), **`data`** (`Buffer` / `Uint8Array` / base64), optional **`id`**, **`label`**, **`platform`**.

### `manifest.json` (optional)

If present next to the PNGs, `screens[]` can list `fileName`, `id`, `label`, `platform`. If missing or invalid, sync still uploads PNGs and infers keys from filenames.

## Browser entry (`@lexoraxiom/appscreenz-sdk`)

Includes DOM capture, PNG downscaling, data URL helpers, and promo-related helpers. Import names from this package in app code processed by your bundler.

## Monorepo demo

From this repo’s `packages/sdk`:

```bash
pnpm run demo:write-output
```

Runs the example under `examples/` (not shipped on npm).