adapty 0.4.0 → 0.6.0-beta.0

package/README.md

@@ -4,7 +4,7 @@
 
 # Adapty CLI
 
-[Adapty Developer CLI](https://adapty.io/docs/developer-cli). Manage apps, products, paywalls, placements, and access levels from your terminal.
+[Adapty Developer CLI](https://adapty.io/docs/developer-cli). Manage apps, products, paywalls, placements, flows, and access levels from your terminal.
 
 ## Installation
 
@@ -77,6 +77,20 @@ adapty placements create --app UUID [flags]
 adapty placements update --app UUID PLACEMENT_ID [flags]
 ```
 
+### Flows
+
+```sh
+adapty flows list --app UUID [--page N] [--page-size N]
+adapty flows get --app UUID FLOW_ID
+adapty flows create --app UUID --name "Name"
+adapty flows config get --app UUID FLOW_ID
+adapty flows config update --app UUID FLOW_ID (--config JSON | --config-file PATH|-) [--remote-configs JSON] [--expected-updated-at MS]
+```
+
+A freshly created flow has no config until the first `flows config update`; `flows config get` returns 404
+until then. Pass `--expected-updated-at` (the `updated_at` from a prior `config get`) to fail instead of
+overwriting a concurrent dashboard edit.
+
 ### Access Levels
 
 ```sh
@@ -136,6 +150,28 @@ adapty asa ads create --ad-group UUID --creative-id 4321 --name "Summer ad"
 adapty asa ads update AD_ID [--name "..."] [--status PAUSED]
 ```
 
+Bulk structure creation submits a whole tree — campaigns with nested ad groups, keywords, negative keywords
+and ads — in one call. The input is a JSON structure (the natural path for an AI agent: generate it, pipe it
+in), or a native Apple Ads template converted server-side. The whole payload is validated before anything is
+created — a rejection lists every bad node; on acceptance the command polls progress and prints the final
+report (`success` / `partial` / `failed`, with per-object failures):
+
+```sh
+adapty asa campaigns bulk-create --file structure.json          # JSON structure, waits and reports
+cat structure.json | adapty asa campaigns bulk-create --file -  # same, from stdin
+adapty asa campaigns bulk-create --file structure.json --no-wait
+adapty asa campaigns bulk-create --from-file Campaign_And_Adgroup_Template.xlsx --org-id 1234567
+adapty asa campaigns bulk-create --from-file keywords_template.csv --org-id 1234567 --preview
+adapty asa campaigns bulk-status OPERATION_ID
+```
+
+The structure is `{campaign_group_id | campaign_group_internal_id, campaigns: [...]}` where each campaign
+node either creates (`payload`) or addresses an existing campaign by id (an *anchor*, optionally carrying
+`update_payload`), and nests `ad_groups` with `keywords`, `negative_keywords` and `ads` the same way.
+`--from-file` takes the native Apple Ads templates and needs `--org-id` (the Apple org id from
+`asa orgs list`); `--preview` prints the converted request without creating anything. Conversion issues are
+reported with their sheet, row and column.
+
 Keywords are always applied as a batch, at most 100 per call, and a partial rejection is reported per item:
 
 ```sh

package/dist/commands/asa/campaigns/bulk-create.d.ts

@@ -0,0 +1,25 @@
+import { Command } from '@oclif/core';
+import type { AsaBulkOperationStateDTO } from '../../../lib/asa-schemas.js';
+export default class AsaCampaignsBulkCreate extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'from-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'org-id': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'poll-interval': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        preview: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        timeout: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        wait: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'idempotency-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<AsaBulkOperationStateDTO | Record<string, unknown>>;
+    private convertTemplate;
+    private countStructure;
+    private formatIssue;
+    private readStructure;
+    private report;
+    private waitForCompletion;
+}

package/dist/commands/asa/campaigns/bulk-create.js

@@ -0,0 +1,177 @@
+import { Command, Flags } from '@oclif/core';
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { asaWrite, createAsaClient, noteReplay } from '../../../lib/asa-client.js';
+import { confirmFlags, confirmMutation } from '../../../lib/asa-confirm.js';
+import { idempotencyFlags } from '../../../lib/asa-flags.js';
+import { printResponse } from '../../../lib/output.js';
+const TERMINAL_STATUSES = new Set(['failed', 'partial', 'success']);
+export default class AsaCampaignsBulkCreate extends Command {
+    static description = 'Create a whole campaign structure (campaigns → ad groups → keywords/negative keywords/ads) in one bulk operation';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa campaigns bulk-create --file structure.json',
+        'cat structure.json | <%= config.bin %> asa campaigns bulk-create --file -',
+        '<%= config.bin %> asa campaigns bulk-create --from-file Campaign_And_Adgroup_Template.xlsx --org-id 1234567',
+        '<%= config.bin %> asa campaigns bulk-create --from-file keywords_template.csv --org-id 1234567 --preview',
+    ];
+    static flags = {
+        ...confirmFlags,
+        ...idempotencyFlags,
+        file: Flags.string({
+            description: 'JSON file with the campaign structure (the POST /bulk-operations/ body); use "-" for stdin',
+            exactlyOne: ['file', 'from-file'],
+        }),
+        'from-file': Flags.string({
+            description: 'Apple Ads bulk template (Campaign_And_Adgroup_Template.xlsx or keywords .csv) to convert and submit',
+        }),
+        'org-id': Flags.integer({
+            description: 'Apple org id (campaign_group_id) the converted template will target; required with --from-file',
+        }),
+        'poll-interval': Flags.integer({ default: 5, description: 'Seconds between progress polls' }),
+        preview: Flags.boolean({
+            description: 'With --from-file: print the converted request and stop, nothing is created',
+        }),
+        timeout: Flags.integer({ default: 900, description: 'Max seconds to wait for the operation to finish' }),
+        wait: Flags.boolean({
+            allowNo: true,
+            default: true,
+            description: 'Poll the operation until it finishes; --no-wait returns the operation id immediately',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(AsaCampaignsBulkCreate);
+        const client = await createAsaClient(this.config);
+        const body = flags['from-file'] ? await this.convertTemplate(client, flags) : await this.readStructure(flags.file);
+        if (flags.preview) {
+            this.log(JSON.stringify(body, null, 2));
+            return body;
+        }
+        const counts = this.countStructure(body);
+        const summary = `Bulk-create: ${counts.campaigns} campaign node(s), ${counts.adGroups} ad group(s), ` +
+            `${counts.keywords} keyword(s), ${counts.negativeKeywords} negative keyword(s), ${counts.ads} ad(s)`;
+        await confirmMutation(this, { body, method: 'POST', path: '/bulk-operations/', summary }, flags.yes);
+        const { replayed, result } = await asaWrite(client, 'post', '/bulk-operations', {
+            body,
+            idempotencyKey: flags['idempotency-key'],
+        });
+        noteReplay(replayed, this.log.bind(this));
+        this.log(`Operation accepted: ${result.operation_id}`);
+        if (!flags.wait) {
+            this.log(`Check progress with: adapty asa campaigns bulk-status ${result.operation_id}`);
+            return { operation_id: result.operation_id };
+        }
+        const state = await this.waitForCompletion(client, result.operation_id, flags['poll-interval'], flags.timeout);
+        this.report(state);
+        return state;
+    }
+    async convertTemplate(client, flags) {
+        if (flags['org-id'] === undefined)
+            this.error('--org-id is required with --from-file.', { exit: 2 });
+        const path = flags['from-file'];
+        let content;
+        try {
+            content = await readFile(path);
+        }
+        catch {
+            this.error(`Cannot read file: ${path}`, { exit: 2 });
+        }
+        const form = new FormData();
+        form.append('file', new Blob([new Uint8Array(content)]), basename(path));
+        form.append('campaign_group_id', String(flags['org-id']));
+        const result = await client.postForm('/bulk-operations/convert', form);
+        for (const warning of result.warnings)
+            this.warn(this.formatIssue(warning));
+        if (result.errors.length > 0 || result.request === null) {
+            for (const issue of result.errors)
+                this.log(this.formatIssue(issue));
+            this.error(`Template conversion failed with ${result.errors.length} error(s); nothing was created.`, { exit: 2 });
+        }
+        return result.request;
+    }
+    countStructure(body) {
+        const counts = { adGroups: 0, ads: 0, campaigns: 0, keywords: 0, negativeKeywords: 0 };
+        const campaigns = Array.isArray(body.campaigns) ? body.campaigns : [];
+        counts.campaigns = campaigns.length;
+        for (const campaign of campaigns) {
+            if (typeof campaign !== 'object' || campaign === null)
+                continue;
+            const campaignNode = campaign;
+            counts.negativeKeywords += Array.isArray(campaignNode.negative_keywords) ? campaignNode.negative_keywords.length : 0;
+            const adGroups = Array.isArray(campaignNode.ad_groups) ? campaignNode.ad_groups : [];
+            counts.adGroups += adGroups.length;
+            for (const adGroup of adGroups) {
+                if (typeof adGroup !== 'object' || adGroup === null)
+                    continue;
+                const adGroupNode = adGroup;
+                counts.keywords += Array.isArray(adGroupNode.keywords) ? adGroupNode.keywords.length : 0;
+                counts.negativeKeywords += Array.isArray(adGroupNode.negative_keywords) ? adGroupNode.negative_keywords.length : 0;
+                counts.ads += Array.isArray(adGroupNode.ads) ? adGroupNode.ads.length : 0;
+            }
+        }
+        return counts;
+    }
+    formatIssue(issue) {
+        const place = [issue.sheet, issue.row === null ? undefined : `row ${issue.row}`, issue.column ?? undefined]
+            .filter(Boolean)
+            .join(', ');
+        return place ? `${place}: ${issue.message}` : issue.message;
+    }
+    async readStructure(source) {
+        let raw;
+        if (source === '-') {
+            const chunks = [];
+            for await (const chunk of process.stdin)
+                chunks.push(chunk);
+            raw = Buffer.concat(chunks).toString('utf8');
+        }
+        else {
+            try {
+                raw = await readFile(source, 'utf8');
+            }
+            catch {
+                this.error(`Cannot read file: ${source}`, { exit: 2 });
+            }
+        }
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            this.error('The structure is not valid JSON.', { exit: 2 });
+        }
+    }
+    report(state) {
+        const { counts } = state;
+        this.log(`Finished: ${state.status} — ${counts.applied}/${counts.total} applied, ${counts.failed} failed`);
+        const failedObjects = state.objects.filter((object) => object.status === 'failed');
+        for (const object of failedObjects) {
+            printResponse(object, this.log.bind(this));
+            this.log('---');
+        }
+        if (state.status === 'failed')
+            this.error('Bulk operation failed.', { exit: 1 });
+        if (state.status === 'partial')
+            this.warn('Some objects were not created — see the failures above.');
+    }
+    async waitForCompletion(client, operationId, pollIntervalSeconds, timeoutSeconds) {
+        const startedAt = Date.now();
+        let lastProgress = '';
+        for (;;) {
+            const state = await client.get(`/bulk-operations/${operationId}`);
+            const progress = `${state.status}: ${state.counts.applied}/${state.counts.total} applied, ${state.counts.failed} failed`;
+            if (progress !== lastProgress) {
+                this.log(progress);
+                lastProgress = progress;
+            }
+            if (TERMINAL_STATUSES.has(state.status))
+                return state;
+            if ((Date.now() - startedAt) / 1000 >= timeoutSeconds) {
+                this.warn(`Still ${state.status} after ${timeoutSeconds}s — check later with: adapty asa campaigns bulk-status ${operationId}`);
+                return state;
+            }
+            await new Promise((resolve) => {
+                setTimeout(resolve, pollIntervalSeconds * 1000);
+            });
+        }
+    }
+}

package/dist/commands/asa/campaigns/bulk-status.d.ts

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+import type { AsaBulkOperationStateDTO } from '../../../lib/asa-schemas.js';
+export default class AsaCampaignsBulkStatus extends Command {
+    static args: {
+        'operation-id': import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        page: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        'page-size': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<AsaBulkOperationStateDTO>;
+}

package/dist/commands/asa/campaigns/bulk-status.js

@@ -0,0 +1,26 @@
+import { Args, Command } from '@oclif/core';
+import { createAsaClient } from '../../../lib/asa-client.js';
+import { asaPaginationFlags } from '../../../lib/asa-flags.js';
+import { isValidUuid, paginationParams } from '../../../lib/flags.js';
+import { printResponse } from '../../../lib/output.js';
+export default class AsaCampaignsBulkStatus extends Command {
+    static args = {
+        'operation-id': Args.string({ description: 'Bulk operation ID returned by bulk-create', required: true }),
+    };
+    static description = 'Progress board of one bulk operation: counts, pipelines and the per-object log';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> asa campaigns bulk-status 660e8400-e29b-41d4-a716-446655440001'];
+    static flags = {
+        ...asaPaginationFlags,
+    };
+    async run() {
+        const { args, flags } = await this.parse(AsaCampaignsBulkStatus);
+        const operationId = args['operation-id'];
+        if (!isValidUuid(operationId))
+            this.error('Invalid operation ID format.', { exit: 2 });
+        const client = await createAsaClient(this.config);
+        const state = await client.get(`/bulk-operations/${operationId}`, paginationParams(flags));
+        printResponse(state, this.log.bind(this));
+        return state;
+    }
+}

package/dist/commands/asa/connect.js

@@ -17,7 +17,8 @@ export default class AsaConnect extends Command {
         this.log(`If the browser doesn't open, visit: ${authUrl}\n`);
         this.log('The link is valid for one hour. Sign in to the Adapty dashboard in that browser first — the last');
         this.log('step is authorized by the dashboard session, not by this CLI.');
-        await open(authUrl).catch(() => false);
+        if (process.stdin.isTTY === true)
+            await open(authUrl).catch(() => false);
         if (!flags.wait)
             return { auth_url: authUrl };
         const deadline = Date.now() + flags.timeout * 1000;

package/dist/commands/auth/login.js

@@ -29,11 +29,13 @@ export default class AuthLogin extends Command {
         }
         this.log(`\nYour code: ${device.user_code}\n`);
         this.log(`If browser doesn't open, visit: ${device.verification_uri_complete}\n`);
-        try {
-            await open(device.verification_uri_complete);
-        }
-        catch {
-            // browser open failed silently — URL already printed
+        if (process.stdin.isTTY === true) {
+            try {
+                await open(device.verification_uri_complete);
+            }
+            catch {
+                // browser open failed silently — URL already printed
+            }
         }
         this.log('Waiting for authorization...');
         let interval = Math.max((device.interval_seconds || 5) * 1000, 5000);

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

@@ -0,0 +1,14 @@
+import { Command } from '@oclif/core';
+import type { FlowConfigDTO } from '../../../lib/api-schemas.js';
+export default class FlowsConfigGet 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: {
+        app: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<FlowConfigDTO>;
+}

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

@@ -0,0 +1,25 @@
+import { Args, Command } from '@oclif/core';
+import { createAuthenticatedClient } from '../../../lib/client-from-config.js';
+import { appFlag, isValidUuid } from '../../../lib/flags.js';
+import { printResponse } from '../../../lib/output.js';
+export default class FlowsConfigGet extends Command {
+    static args = {
+        flow_id: Args.string({ description: 'Flow ID (UUID)', required: true }),
+    };
+    static description = 'Read the flow builder config (404 until the config has been written at least once)';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> flows config get --app UUID 550e8400-e29b-41d4-a716-446655440000'];
+    static flags = {
+        ...appFlag,
+    };
+    async run() {
+        const { args, flags } = await this.parse(FlowsConfigGet);
+        if (!isValidUuid(args.flow_id)) {
+            this.error('Invalid flow ID format.', { exit: 2 });
+        }
+        const client = await createAuthenticatedClient(this.config);
+        const result = await client.get(`/apps/${flags.app}/flows/${args.flow_id}/config`);
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

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

@@ -0,0 +1,21 @@
+import { Command } from '@oclif/core';
+import type { FlowConfigDTO } from '../../../lib/api-schemas.js';
+export default class FlowsConfigUpdate 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>;
+        'expected-updated-at': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'remote-configs': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        app: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<FlowConfigDTO>;
+    private parseJson;
+    private readConfig;
+    private readStdin;
+}

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

@@ -0,0 +1,84 @@
+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 FlowsConfigUpdate extends Command {
+    static args = {
+        flow_id: Args.string({ description: 'Flow ID (UUID)', required: true }),
+    };
+    static description = 'Write the flow builder config (creates the first version, or edits/forks the current one)';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> flows config update --app UUID FLOW_UUID --config-file config.json',
+        'cat config.json | <%= config.bin %> flows config update --app UUID FLOW_UUID --config-file -',
+        '<%= config.bin %> flows config update --app UUID FLOW_UUID --config \'{"screens":[],"locales":[]}\' --expected-updated-at 1755001800000',
+    ];
+    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'],
+        }),
+        'expected-updated-at': Flags.integer({
+            description: 'Optimistic lock: the `updated_at` from a prior config read. Omit for last-write-wins.',
+        }),
+        'remote-configs': Flags.string({
+            description: 'JSON array of remote config entries: [{locale, data}]',
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(FlowsConfigUpdate);
+        if (!isValidUuid(args.flow_id)) {
+            this.error('Invalid flow ID format.', { exit: 2 });
+        }
+        const config = await this.readConfig(flags);
+        const body = { config };
+        if (flags['remote-configs'] !== undefined) {
+            body.remote_configs = this.parseJson(flags['remote-configs'], '--remote-configs');
+        }
+        if (flags['expected-updated-at'] !== undefined) {
+            body.expected_updated_at = flags['expected-updated-at'];
+        }
+        const client = await createAuthenticatedClient(this.config);
+        const result = await client.put(`/apps/${flags.app}/flows/${args.flow_id}/config`, body);
+        this.log('Flow config saved!');
+        printResponse(result, this.log.bind(this));
+        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/commands/flows/create.d.ts

@@ -0,0 +1,12 @@
+import { Command } from '@oclif/core';
+import type { FlowDTO } from '../../lib/api-schemas.js';
+export default class FlowsCreate extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        name: 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<FlowDTO>;
+}

package/dist/commands/flows/create.js

@@ -0,0 +1,22 @@
+import { Command, Flags } from '@oclif/core';
+import { createAuthenticatedClient } from '../../lib/client-from-config.js';
+import { appFlag } from '../../lib/flags.js';
+import { printResponse } from '../../lib/output.js';
+export default class FlowsCreate extends Command {
+    static description = 'Create a flow (row only — write its config with `flows config update`)';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> flows create --app UUID --name "Onboarding"'];
+    static flags = {
+        ...appFlag,
+        name: Flags.string({ description: 'Flow name', required: true }),
+    };
+    async run() {
+        const { flags } = await this.parse(FlowsCreate);
+        const client = await createAuthenticatedClient(this.config);
+        const body = { name: flags.name };
+        const result = await client.post(`/apps/${flags.app}/flows`, body);
+        this.log('Flow created!');
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

package/dist/commands/flows/get.d.ts

@@ -0,0 +1,14 @@
+import { Command } from '@oclif/core';
+import type { FlowDTO } from '../../lib/api-schemas.js';
+export default class FlowsGet 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: {
+        app: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<FlowDTO>;
+}

package/dist/commands/flows/get.js

@@ -0,0 +1,25 @@
+import { Args, Command } from '@oclif/core';
+import { createAuthenticatedClient } from '../../lib/client-from-config.js';
+import { appFlag, isValidUuid } from '../../lib/flags.js';
+import { printResponse } from '../../lib/output.js';
+export default class FlowsGet extends Command {
+    static args = {
+        flow_id: Args.string({ description: 'Flow ID (UUID)', required: true }),
+    };
+    static description = 'Get flow details';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> flows get --app UUID 550e8400-e29b-41d4-a716-446655440000'];
+    static flags = {
+        ...appFlag,
+    };
+    async run() {
+        const { args, flags } = await this.parse(FlowsGet);
+        if (!isValidUuid(args.flow_id)) {
+            this.error('Invalid flow ID format.', { exit: 2 });
+        }
+        const client = await createAuthenticatedClient(this.config);
+        const result = await client.get(`/apps/${flags.app}/flows/${args.flow_id}`);
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

package/dist/commands/flows/list.d.ts

@@ -0,0 +1,14 @@
+import { Command } from '@oclif/core';
+import type { FlowDTO } from '../../lib/api-schemas.js';
+import { type PaginatedResponse } from '../../lib/flags.js';
+export default class FlowsList extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        page: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        'page-size': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        app: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<PaginatedResponse<FlowDTO>>;
+}

package/dist/commands/flows/list.js

@@ -0,0 +1,20 @@
+import { Command } from '@oclif/core';
+import { createAuthenticatedClient } from '../../lib/client-from-config.js';
+import { appFlag, paginationFlags, paginationParams } from '../../lib/flags.js';
+import { printList } from '../../lib/output.js';
+export default class FlowsList extends Command {
+    static description = 'List flows for an app';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> flows list --app 550e8400-...'];
+    static flags = {
+        ...appFlag,
+        ...paginationFlags,
+    };
+    async run() {
+        const { flags } = await this.parse(FlowsList);
+        const client = await createAuthenticatedClient(this.config);
+        const result = await client.get(`/apps/${flags.app}/flows`, paginationParams(flags));
+        printList(result.data, this.log.bind(this), result.meta.pagination);
+        return result;
+    }
+}

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

@@ -20,6 +20,7 @@ export declare class ApiClient {
     constructor(opts?: ApiClientOptions);
     get<T = unknown>(path: string, params?: QueryParams): Promise<T>;
     post<T = unknown>(path: string, body?: unknown, params?: QueryParams, opts?: RequestOptions): Promise<T>;
+    postForm<T = unknown>(path: string, form: FormData, params?: QueryParams, opts?: RequestOptions): Promise<T>;
     put<T = unknown>(path: string, body?: unknown, params?: QueryParams, opts?: RequestOptions): Promise<T>;
     private buildUrl;
     private isRetryableRateLimit;

package/dist/lib/api-client.js

@@ -29,6 +29,9 @@ export class ApiClient {
             method: 'POST',
         }, opts);
     }
+    async postForm(path, form, params, opts) {
+        return this.request(this.buildUrl(path, params), { body: form, method: 'POST' }, opts);
+    }
     async put(path, body, params, opts) {
         return this.request(this.buildUrl(path, params), {
             body: body ? JSON.stringify(body) : undefined,
@@ -60,7 +63,7 @@ export class ApiClient {
         const headers = {
             'User-Agent': this.userAgent,
         };
-        if (init.body) {
+        if (init.body && !(init.body instanceof FormData)) {
             headers['Content-Type'] = 'application/json';
         }
         if (this.token) {