adapty 0.6.0 → 0.6.1-beta.0

package/README.md

@@ -256,6 +256,33 @@ and the outcome shows up in `adapty asa automations runs`.
 | `--page`      | Page number (default: 1)               |
 | `--page-size` | Items per page (default: 20, max: 100; `asa` commands: default 100, max 1000) |
 
+## Paywall Preview
+
+`adapty flows config preview <config_file>` turns a local flow config into a render URL. On a TTY it opens the
+browser; piped or with `--json` it prints the URL alone. Screenshotting is the caller's job — the CLI only
+builds the URL.
+
+> **Small configs only.** This is a quick-look escape hatch. The config travels in the URL fragment, and past
+> roughly **32KB of pretty-printed JSON** the render page becomes slow and unreliable. Trim to the screen you
+> care about, or preview the saved flow in the dashboard builder instead.
+
+> **That URL is huge.** Even a config the page renders happily produces thousands of characters, and a 668KB
+> flow yields ~113,000. Nobody should read it — **agents especially should never let it into their context.**
+> Pipe it into whatever captures the screenshot:
+>
+> ```sh
+> adapty flows config preview flow.json --screen scr_abc | node capture.mjs --out shot.png
+>
+> # or, for a tool that wants a flag instead of stdin:
+> node capture.mjs --url "$(adapty flows config preview flow.json --screen scr_abc)" --out shot.png
+> ```
+>
+> Prefer the pipe: it has no size limit, while an argument is capped by the shell (~1MB, so a config around
+> 6MB).
+
+See [skills/adapty-cli/references/cli-commands.md](skills/adapty-cli/references/cli-commands.md#preview) for
+the flags and the size ceiling.
+
 ## Environment Variables
 
 | Variable             | Description                                                                             |
@@ -263,6 +290,7 @@ and the outcome shows up in `adapty asa automations runs`.
 | `ADAPTY_TOKEN`       | Override stored auth token                                                              |
 | `ADAPTY_API_URL`     | Override Developer API base URL (default: `https://api-admin.adapty.io/api/v1/developer`) |
 | `ADAPTY_ASA_API_URL` | Override Apple Search Ads base URL (default: `https://api-asa-admin.adapty.io/api/v1/cli`) |
+| `ADAPTY_APP_URL`     | Override dashboard base URL (default: `https://app.adapty.io`). Used by `flows config preview` for the fixed `/flow-preview` route, and by `auth login` to keep the verification link on that host |
 
 The two API URLs are independent: pointing `ADAPTY_API_URL` at a staging host leaves `adapty asa` on the ASA
 default, and the other way round.

package/dist/commands/auth/login.d.ts

@@ -3,4 +3,6 @@ export default class AuthLogin extends Command {
     static description: string;
     static examples: string[];
     run(): Promise<void>;
+    /** Keeps the browser on the configured dashboard host, when ADAPTY_APP_URL asks for one. */
+    private verificationUrl;
 }

package/dist/commands/auth/login.js

@@ -1,6 +1,7 @@
 import { Command } from '@oclif/core';
 import open from 'open';
 import { ApiClient } from '../../lib/api-client.js';
+import { onAppHost } from '../../lib/app-url.js';
 import { buildUserAgent } from '../../lib/client-from-config.js';
 import { readConfig, writeConfig } from '../../lib/config.js';
 import { ApiError } from '../../lib/errors.js';
@@ -27,11 +28,12 @@ export default class AuthLogin extends Command {
         catch (error) {
             this.error(error instanceof Error ? error.message : 'Failed to initiate auth flow', { exit: 1 });
         }
+        const verificationUrl = this.verificationUrl(device.verification_uri_complete);
         this.log(`\nYour code: ${device.user_code}\n`);
-        this.log(`If browser doesn't open, visit: ${device.verification_uri_complete}\n`);
+        this.log(`If browser doesn't open, visit: ${verificationUrl}\n`);
         if (process.stdin.isTTY === true) {
             try {
-                await open(device.verification_uri_complete);
+                await open(verificationUrl);
             }
             catch {
                 // browser open failed silently — URL already printed
@@ -106,4 +108,13 @@ export default class AuthLogin extends Command {
             process.removeListener('SIGINT', onSignal);
         }
     }
+    /** Keeps the browser on the configured dashboard host, when ADAPTY_APP_URL asks for one. */
+    verificationUrl(issuedUrl) {
+        try {
+            return onAppHost(issuedUrl);
+        }
+        catch (error) {
+            this.error(error instanceof Error ? error.message : String(error), { exit: 2 });
+        }
+    }
 }

package/dist/commands/flows/config/preview.d.ts

@@ -0,0 +1,18 @@
+import { Command } from '@oclif/core';
+export interface PreviewResult {
+    render_url: string;
+}
+export default class FlowsConfigPreview extends Command {
+    static args: {
+        config_file: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        device: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        orientation: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        screen: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<PreviewResult>;
+}

package/dist/commands/flows/config/preview.js

@@ -0,0 +1,74 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import open from 'open';
+import { APP_URL_ENV_VAR } from '../../../lib/app-url.js';
+import { buildRenderUrl, DEFAULT_DEVICE_ID, DEFAULT_ORIENTATION, normalizePreviewConfig, ORIENTATIONS, } from '../../../lib/preview.js';
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export default class FlowsConfigPreview extends Command {
+    static args = {
+        config_file: Args.string({ description: 'Path to a local flow config JSON file', required: true }),
+    };
+    static description = `Build a render URL for a local flow config and open it. A quick-look escape hatch for small configs: the whole config rides in the URL fragment, and past roughly 32KB of pretty-printed JSON the render page gets slow and unreliable. Opens the browser on a TTY; when piped or with --json, prints the URL alone — and that URL is long (~113K characters for a 668KB flow), so pipe it into whatever takes the screenshot ("| node capture.mjs") or pass it with --url and command substitution. Never print or read it: agents burn context for zero information. The render host comes from $${APP_URL_ENV_VAR}.`;
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> flows config preview ./config.json',
+        '<%= config.bin %> flows config preview ./config.json --screen welcome --device ipad-pro --orientation landscape',
+        '# pipe the URL straight into a screenshot tool, never print it\n<%= config.bin %> flows config preview ./config.json | node capture.mjs --out shot.png',
+        '# or pass it as an argument, for tools that want a flag\nnode capture.mjs --url "$(<%= config.bin %> flows config preview ./config.json)" --out shot.png',
+    ];
+    static flags = {
+        device: Flags.string({ default: DEFAULT_DEVICE_ID, description: 'Device frame to render in' }),
+        orientation: Flags.string({
+            default: DEFAULT_ORIENTATION,
+            description: 'Device orientation to render in',
+            options: [...ORIENTATIONS],
+        }),
+        screen: Flags.string({ description: "Screen ID to render (default: the flow's first screen)" }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(FlowsConfigPreview);
+        const configPath = resolve(args.config_file);
+        let raw;
+        try {
+            raw = JSON.parse(await readFile(configPath, 'utf8'));
+        }
+        catch (error) {
+            this.error(`Could not read config file ${configPath}: ${describeError(error)}`, { exit: 2 });
+        }
+        let payload;
+        try {
+            payload = normalizePreviewConfig(raw);
+        }
+        catch (error) {
+            this.error(describeError(error), { exit: 2 });
+        }
+        let renderUrl;
+        try {
+            renderUrl = buildRenderUrl({ device: flags.device, orientation: flags.orientation, screen: flags.screen }, payload);
+        }
+        catch (error) {
+            this.error(describeError(error), { exit: 2 });
+        }
+        const result = { render_url: renderUrl };
+        if (this.jsonEnabled())
+            return result;
+        // Piped output stays a bare URL so it composes — the whole config rides in the fragment, which
+        // is why a TTY gets the browser opened instead of a screenful of base64.
+        if (process.stdout.isTTY !== true) {
+            this.log(renderUrl);
+            return result;
+        }
+        const target = [flags.screen ?? 'first screen', flags.device, flags.orientation].join(', ');
+        try {
+            await open(renderUrl);
+            this.log(`Opened the preview in your browser (${target}).`);
+        }
+        catch {
+            this.log(renderUrl);
+        }
+        return result;
+    }
+}

package/dist/commands/flows/config/validate.d.ts

@@ -0,0 +1,20 @@
+import { Command } from '@oclif/core';
+import type { FlowConfigValidationDTO } from '../../../lib/api-schemas.js';
+export default class FlowsConfigValidate extends Command {
+    static args: {
+        flow_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'config-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        source: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        app: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<FlowConfigValidationDTO>;
+    private parseJson;
+    private readConfig;
+    private readStdin;
+}

package/dist/commands/flows/config/validate.js

@@ -0,0 +1,81 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { readFile } from 'node:fs/promises';
+import { createAuthenticatedClient } from '../../../lib/client-from-config.js';
+import { appFlag, isValidUuid } from '../../../lib/flags.js';
+import { printResponse } from '../../../lib/output.js';
+export default class FlowsConfigValidate extends Command {
+    static args = {
+        flow_id: Args.string({ description: 'Flow ID (UUID)', required: true }),
+    };
+    static description = 'Check whether a builder config is publishable (advisory; does not save). Exits non-zero when the config is not publishable.';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> flows config validate --app UUID FLOW_UUID --config-file config.json',
+        'cat config.json | <%= config.bin %> flows config validate --app UUID FLOW_UUID --config-file -',
+        '<%= config.bin %> flows config validate --app UUID FLOW_UUID --config \'{"screens":[],"locales":[]}\'',
+    ];
+    static flags = {
+        ...appFlag,
+        config: Flags.string({
+            description: 'Builder config as a JSON string',
+            exactlyOne: ['config', 'config-file'],
+        }),
+        'config-file': Flags.string({
+            description: 'JSON file with the builder config, or - to read stdin',
+            exactlyOne: ['config', 'config-file'],
+        }),
+        source: Flags.string({
+            default: 'adapty-cli',
+            description: 'Caller attribution, sent as X-Adapty-Source (e.g. byo-cli)',
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(FlowsConfigValidate);
+        if (!isValidUuid(args.flow_id)) {
+            this.error('Invalid flow ID format.', { exit: 2 });
+        }
+        const config = await this.readConfig(flags);
+        const body = { config };
+        const client = await createAuthenticatedClient(this.config);
+        const result = await client.post(`/apps/${flags.app}/flows/${args.flow_id}/config/validate`, body, undefined, { headers: { 'X-Adapty-Source': flags.source } });
+        this.log(result.valid ? 'Config is publishable.' : 'Config is NOT publishable.');
+        printResponse(result, this.log.bind(this));
+        // Advisory endpoint always returns HTTP 200; surface the verdict as an exit code so scripts and agents
+        // can gate on it. The JSON/`valid` field stays the source of truth for programmatic consumers.
+        if (!result.valid) {
+            process.exitCode = 1;
+        }
+        return result;
+    }
+    parseJson(raw, label) {
+        try {
+            return JSON.parse(raw);
+        }
+        catch (error) {
+            this.error(`Invalid ${label} JSON: ${error instanceof Error ? error.message : String(error)}`, { exit: 2 });
+        }
+    }
+    async readConfig(flags) {
+        if (flags.config !== undefined) {
+            return this.parseJson(flags.config, '--config');
+        }
+        const path = flags['config-file'];
+        if (path === undefined) {
+            this.error('Provide --config or --config-file.', { exit: 2 });
+        }
+        let raw;
+        try {
+            raw = path === '-' ? await this.readStdin() : await readFile(path, 'utf8');
+        }
+        catch {
+            this.error(`Could not read ${path}.`, { exit: 2 });
+        }
+        return this.parseJson(raw, path);
+    }
+    async readStdin() {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        return Buffer.concat(chunks).toString('utf8');
+    }
+}

package/dist/lib/api-schemas.d.ts

@@ -101,6 +101,21 @@ export interface FlowConfigWriteRequestDTO {
     expected_updated_at?: null | number;
     remote_configs?: FlowRemoteConfigDTO[];
 }
+export interface FlowConfigValidateRequestDTO {
+    config: Record<string, unknown>;
+}
+export interface FlowConfigIssueDTO {
+    /** Machine code, relayed from the transformer; absent until it reports path-level diagnostics. */
+    code?: null | string;
+    message: string;
+    /** Location of the issue; absent until the transformer reports path-level diagnostics. */
+    path?: null | string;
+    severity: string;
+}
+export interface FlowConfigValidationDTO {
+    issues: FlowConfigIssueDTO[];
+    valid: boolean;
+}
 export interface SegmentDTO {
     description: null | string;
     id: string;

package/dist/lib/app-url.d.ts

@@ -0,0 +1,10 @@
+export declare const APP_URL_ENV_VAR = "ADAPTY_APP_URL";
+export declare const DEFAULT_APP_URL = "https://app.adapty.io";
+/** Builds a dashboard URL for a fixed route, e.g. the flow preview page. */
+export declare function appUrl(path: string): URL;
+/**
+ * Moves a link the API issued (the device-flow verification URI) onto the configured dashboard
+ * host, so pointing the CLI at a local or staging dashboard keeps the browser there too. Without
+ * ADAPTY_APP_URL the link is left exactly as issued — the API is free to serve it from any host.
+ */
+export declare function onAppHost(issuedUrl: string): string;

package/dist/lib/app-url.js

@@ -0,0 +1,33 @@
+export const APP_URL_ENV_VAR = 'ADAPTY_APP_URL';
+export const DEFAULT_APP_URL = 'https://app.adapty.io';
+/** Dashboard origin: ADAPTY_APP_URL when set, production otherwise. Only its origin is used. */
+function appBaseUrl() {
+    const base = process.env[APP_URL_ENV_VAR] ?? DEFAULT_APP_URL;
+    try {
+        return new URL(base);
+    }
+    catch {
+        throw new Error(`Invalid ${APP_URL_ENV_VAR}: ${base}`);
+    }
+}
+/** Builds a dashboard URL for a fixed route, e.g. the flow preview page. */
+export function appUrl(path) {
+    return new URL(path, appBaseUrl());
+}
+/**
+ * Moves a link the API issued (the device-flow verification URI) onto the configured dashboard
+ * host, so pointing the CLI at a local or staging dashboard keeps the browser there too. Without
+ * ADAPTY_APP_URL the link is left exactly as issued — the API is free to serve it from any host.
+ */
+export function onAppHost(issuedUrl) {
+    if (!process.env[APP_URL_ENV_VAR])
+        return issuedUrl;
+    let issued;
+    try {
+        issued = new URL(issuedUrl);
+    }
+    catch {
+        return issuedUrl;
+    }
+    return appUrl(`${issued.pathname}${issued.search}${issued.hash}`).toString();
+}

package/dist/lib/preview.d.ts

@@ -0,0 +1,27 @@
+/** The render route is fixed; only its host is configurable, via ADAPTY_APP_URL. */
+export declare const PREVIEW_PATH = "/flow-preview";
+export declare const DEFAULT_DEVICE_ID = "iphone-14";
+/** Orientations the render page accepts; anything else falls back to its own default. */
+export declare const ORIENTATIONS: readonly ["landscape", "portrait"];
+export declare const DEFAULT_ORIENTATION = "portrait";
+/** Payload the render page expects. Wire format shared with the UI, hence camelCase. */
+export interface PreviewPayload {
+    flow: Record<string, unknown>;
+    remoteConfigs: unknown[];
+}
+/**
+ * Accepts either a dashboard-api envelope (`{config, remote_configs, ...}`) or a bare
+ * builder config, and returns the shape the render page injects.
+ *
+ * `screens` must be an array: that is exactly what the page's own payload guard checks
+ * before it treats the payload as a builder draft, so a config without it would be
+ * rejected there instead — better to say so here, against the file the user named.
+ */
+export declare function normalizePreviewConfig(raw: unknown): PreviewPayload;
+export interface RenderTarget {
+    device: string;
+    orientation: string;
+    /** Omitted lets the render page fall back to the flow's first screen. */
+    screen?: string;
+}
+export declare function buildRenderUrl(target: RenderTarget, payload: PreviewPayload): string;

package/dist/lib/preview.js

@@ -0,0 +1,48 @@
+import { gzipSync } from 'node:zlib';
+import { appUrl } from './app-url.js';
+/** The render route is fixed; only its host is configurable, via ADAPTY_APP_URL. */
+export const PREVIEW_PATH = '/flow-preview';
+export const DEFAULT_DEVICE_ID = 'iphone-14';
+/** Orientations the render page accepts; anything else falls back to its own default. */
+export const ORIENTATIONS = ['landscape', 'portrait'];
+export const DEFAULT_ORIENTATION = 'portrait';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Accepts either a dashboard-api envelope (`{config, remote_configs, ...}`) or a bare
+ * builder config, and returns the shape the render page injects.
+ *
+ * `screens` must be an array: that is exactly what the page's own payload guard checks
+ * before it treats the payload as a builder draft, so a config without it would be
+ * rejected there instead — better to say so here, against the file the user named.
+ */
+export function normalizePreviewConfig(raw) {
+    if (!isRecord(raw)) {
+        throw new Error('Config file must contain a JSON object.');
+    }
+    const envelopeConfig = isRecord(raw.config) ? raw.config : null;
+    const flow = envelopeConfig ?? raw;
+    if (!Array.isArray(flow.screens)) {
+        throw new TypeError('Unrecognized config file. Expected a dashboard-api envelope with a `config` object, or a bare builder config — either way `screens` must be an array.');
+    }
+    const remoteConfigs = envelopeConfig && Array.isArray(raw.remote_configs) ? raw.remote_configs : [];
+    return { flow, remoteConfigs };
+}
+/**
+ * Fragment wire format shared with the render page: bare `base64url(gzip(utf8(JSON)))`, no
+ * prefix — the page compresses unconditionally too, so there is no plain shape to mark it
+ * apart from. Node's base64url already omits the `=` padding the page strips.
+ */
+function encodeConfigFragment(payload) {
+    return gzipSync(Buffer.from(JSON.stringify(payload), 'utf8')).toString('base64url');
+}
+export function buildRenderUrl(target, payload) {
+    const url = appUrl(PREVIEW_PATH);
+    if (target.screen)
+        url.searchParams.set('screen', target.screen);
+    url.searchParams.set('device', target.device);
+    url.searchParams.set('orientation', target.orientation);
+    url.hash = `config=${encodeConfigFragment(payload)}`;
+    return url.toString();
+}