adapty 0.8.7 → 0.8.8

package/README.md

@@ -387,6 +387,33 @@ too. A burst of 429s puts the token into an escalating cool-down (`cli_cooldown_
 not waiting out the pause in a loop. An automation run is queued rather than awaited: `run` prints a run ID
 and the outcome shows up in `adapty asa automations runs`.
 
+### Attribution
+
+Attribution analytics across ad networks live under `adapty attribution` and talk to the attribution service
+rather than the Developer API, with the same token. `report` and `values` take `--app`; the two catalogs take no
+app.
+
+```sh
+adapty attribution metrics       # metric names a report can ask for
+adapty attribution dimensions    # dimensions a report can group or filter by
+adapty attribution values --app APP_UUID --date-from 2026-08-01 --date-to 2026-08-31 --dimension campaign
+adapty attribution report --app APP_UUID --date-from 2026-08-01 --date-to 2026-08-31 \
+  --metrics spend,installs,d7_roas --group-by date,campaign --granularity week \
+  --filter country=US,GB --revenue-basis proceeds --sort spend:desc
+```
+
+Dates are inclusive days in the app's timezone. `--metrics` and `--group-by` take repeated flags or
+comma-separated lists; `--filter dimension=value[,value]` repeats, where one value matches exactly and several
+match any of them; `--sort field[:asc|desc]` is ascending unless told otherwise. `--json` prints the service's
+answer unchanged (`{"success", "data", "meta"}`). In the human view a metric that cannot be computed prints
+`—`, never `0`.
+
+A rejected request exits 4 and carries the service's `error_code` in the `--json` error, e.g.
+`attribution_unknown_metric` or `attribution_access_required` (the company has no attribution access — logging
+in again does not help). `report` and `values` are sent once and never retried: on `attribution_busy` (429) or
+an unavailable service (503), wait for the `Retry-After` the service sent before running the query again. The
+`--json` error carries that wait as `retry_after_seconds`, whenever the service sent one.
+
 ### Global Flags
 
 | Flag          | Description                            |
@@ -430,10 +457,11 @@ the flags and the size ceiling.
 | `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_ATTRIBUTION_API_URL` | Override attribution base URL (default: `https://api-ua.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.
+The API URLs are independent: pointing `ADAPTY_API_URL` at a staging host leaves `adapty asa` and
+`adapty attribution` on their own defaults, and the other way round.
 
 ## Claude Code Skill
 

package/dist/cli/base/adapty/adapty-command.d.ts

@@ -1,9 +1,6 @@
 import { BaseCommand } from '../base-command.js';
-import type { ResolvedSession } from './openSession.js';
 import type { Adapty } from '../../../sdk/adapty/index.js';
-export type AuthenticatedSession = ResolvedSession & {
-    token: string;
-};
+import type { AuthenticatedSession } from '../session.js';
 /**
  * Commands that require a token; auth commands other than `whoami` also work without one.
  *

package/dist/cli/base/adapty/build.d.ts

@@ -1,11 +1,5 @@
-import type { ResolvedSession } from './openSession.js';
 import type { Adapty } from '../../../sdk/adapty/index.js';
-import type { Config } from '@oclif/core';
-type CommandContext = {
-    config: Config;
-    signal: AbortSignal;
-    warn: (message: string) => void;
-};
+import type { CommandContext } from '../base-command.js';
+import type { ResolvedSession } from '../session.js';
 /** Shared by authenticated commands and login/revoke, which can run without a token. */
 export declare const build: (session: ResolvedSession, context: CommandContext) => Adapty;
-export {};

package/dist/cli/base/adapty/index.d.ts

@@ -1,5 +1,4 @@
 export { AdaptyCommand } from './adapty-command.js';
 export { build } from './build.js';
-export { openSession } from './openSession.js';
-export type { AuthenticatedSession } from './adapty-command.js';
-export type { ResolvedSession } from './openSession.js';
+export { openSession, resolveSession } from './openSession.js';
+export type { AuthenticatedSession, ResolvedSession } from '../session.js';

package/dist/cli/base/adapty/index.js

@@ -1,3 +1,3 @@
 export { AdaptyCommand } from './adapty-command.js';
 export { build } from './build.js';
-export { openSession } from './openSession.js';
+export { openSession, resolveSession } from './openSession.js';

package/dist/cli/base/adapty/openSession.d.ts

@@ -1,22 +1,5 @@
-import type { SessionStore, SessionUser } from '../../../sdk/core/session.js';
+import type { ResolvedSession } from '../session.js';
 import type { Config } from '@oclif/core';
-/**
- * The CLI's world resolved into what the sdk asks for: where to talk, as whom, and where the
- * session lives. Env vars are read here and only here — the sdk never touches process.env, which
- * is what lets the same product code run under an MCP server.
- */
-export type ResolvedSession = {
-    apiUrl: string;
-    /**
-     * Where the token came from. With ADAPTY_TOKEN in play, "no token in the file" and "not
-     * authenticated" are different answers, and `auth status` has to say which one it means.
-     */
-    source: 'env' | 'file' | 'none';
-    /** The store itself, not its path: `auth login`/`logout` write through it. */
-    store: SessionStore;
-    token?: string | undefined;
-    user?: SessionUser | undefined;
-};
-/** ADAPTY_TOKEN wins over the stored session, as the published CLI already does. */
+/** The shared token and store, sent to the developer API: ADAPTY_API_URL, or the default. */
 export declare const resolveSession: (config: Config) => Promise<ResolvedSession>;
 export declare const openSession: (config: Config) => Promise<ResolvedSession>;

package/dist/cli/base/adapty/openSession.js

@@ -1,20 +1,10 @@
 import { DEFAULT_ADAPTY_API_URL } from '../../../sdk/adapty/index.js';
-import { createFileSessionStore } from '../../../sdk/core/session.js';
-/** ADAPTY_TOKEN wins over the stored session, as the published CLI already does. */
-export const resolveSession = async (config) => {
-    const apiUrl = process.env.ADAPTY_API_URL ?? DEFAULT_ADAPTY_API_URL;
-    // oclif's configDir already knows XDG on unix and LOCALAPPDATA on Windows
-    const store = createFileSessionStore(config.configDir);
-    const envToken = process.env.ADAPTY_TOKEN;
-    if (envToken !== undefined && envToken !== '') {
-        return { apiUrl, source: 'env', store, token: envToken };
-    }
-    const stored = await store.load();
-    if (stored === undefined) {
-        return { apiUrl, source: 'none', store };
-    }
-    return { apiUrl, source: 'file', store, token: stored.token, user: stored.user };
-};
+import { loadSession } from '../session.js';
+/** The shared token and store, sent to the developer API: ADAPTY_API_URL, or the default. */
+export const resolveSession = async (config) => ({
+    apiUrl: process.env.ADAPTY_API_URL ?? DEFAULT_ADAPTY_API_URL,
+    ...await loadSession(config),
+});
 export const openSession = async (config) => {
     const session = await resolveSession(config);
     if (session.apiUrl !== DEFAULT_ADAPTY_API_URL) {

package/dist/cli/base/attribution/attribution-command.d.ts

@@ -0,0 +1,16 @@
+import { BaseCommand } from '../base-command.js';
+import type { Attribution } from '../../../sdk/attribution/index.js';
+import type { AuthenticatedSession } from '../session.js';
+/**
+ * Commands of the attribution backend, which all require a token. The same shape as AdaptyCommand:
+ * the session is resolved in init(), the token is demanded and the sdk built only on first access,
+ * so a command that validates its input first answers bad input with exit 2, not "Not authenticated".
+ */
+export declare abstract class AttributionCommand extends BaseCommand {
+    #private;
+    static enableJsonFlag: boolean;
+    protected get attribution(): Attribution;
+    /** Narrowed once here, so nothing downstream re-checks the token. */
+    protected get session(): AuthenticatedSession;
+    protected init(): Promise<void>;
+}

package/dist/cli/base/attribution/attribution-command.js

@@ -0,0 +1,42 @@
+import { AuthRequiredError } from '../../../sdk/core/errors.js';
+import { BaseCommand } from '../base-command.js';
+import { build } from './build.js';
+import { openSession } from './openSession.js';
+/**
+ * Commands of the attribution backend, which all require a token. The same shape as AdaptyCommand:
+ * the session is resolved in init(), the token is demanded and the sdk built only on first access,
+ * so a command that validates its input first answers bad input with exit 2, not "Not authenticated".
+ */
+export class AttributionCommand extends BaseCommand {
+    // Keep one own static so oclif's manifest cache walks through this intermediate class and
+    // includes statics inherited from BaseCommand.
+    static enableJsonFlag = true;
+    #attribution;
+    #resolved;
+    get attribution() {
+        this.#attribution ??= build(this.session, {
+            config: this.config,
+            signal: this.signal,
+            warn: message => this.warn(message),
+        });
+        return this.#attribution;
+    }
+    /** Narrowed once here, so nothing downstream re-checks the token. */
+    get session() {
+        const resolved = this.#resolved;
+        if (resolved === undefined) {
+            // A bug, not a user error, and deliberately not an SdkError: it lands as exit 1 with a
+            // stack instead of passing for a normal scenario.
+            throw new Error('session is available only after init()');
+        }
+        if (resolved.token === undefined) {
+            throw new AuthRequiredError('missing');
+        }
+        return { ...resolved, token: resolved.token };
+    }
+    async init() {
+        await super.init();
+        // Read here, demanded lazily: this.parse() runs after init(), and input errors come first.
+        this.#resolved = await openSession(this.config);
+    }
+}

package/dist/cli/base/attribution/build.d.ts

@@ -0,0 +1,5 @@
+import type { Attribution } from '../../../sdk/attribution/index.js';
+import type { CommandContext } from '../base-command.js';
+import type { ResolvedSession } from '../session.js';
+/** Mirrors the Adapty build: the retry warning is heard only on the catalog reads, the POSTs never retry. */
+export declare const build: (session: ResolvedSession, context: CommandContext) => Attribution;

package/dist/cli/base/attribution/build.js

@@ -0,0 +1,12 @@
+import { buildUserAgent } from '../../../lib/client-from-config.js';
+import { createAttribution } from '../../../sdk/attribution/index.js';
+/** Mirrors the Adapty build: the retry warning is heard only on the catalog reads, the POSTs never retry. */
+export const build = (session, context) => createAttribution({
+    baseUrl: session.apiUrl,
+    onRetry: ({ attempt, delayMs }) => {
+        context.warn(`Request failed, retrying in ${delayMs / 1000}s (attempt ${attempt + 1})`);
+    },
+    signal: context.signal,
+    token: session.token,
+    userAgent: buildUserAgent(context.config),
+});

package/dist/cli/base/attribution/flags.d.ts

@@ -0,0 +1,16 @@
+/** An inclusive day range, both ends required. */
+export declare const periodFlags: {
+    'date-from': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    'date-to': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+};
+export declare const revenueBasisFlag: {
+    'revenue-basis': import("@oclif/core/interfaces").OptionFlag<"gross" | "proceeds" | "net" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};
+/** Where the period flags meet the sdk's field names. */
+export declare const periodParams: (flags: {
+    "date-from": string;
+    "date-to": string;
+}) => {
+    dateFrom: string;
+    dateTo: string;
+};

package/dist/cli/base/attribution/flags.js

@@ -0,0 +1,28 @@
+import { Flags } from '@oclif/core';
+import { ISO_DATE, revenueBases } from '../../../sdk/attribution/index.js';
+import { usageError } from '../../errors.js';
+/** The shape only: whether the day exists and the order of the two are sdk rules. */
+const dateParser = (input) => (ISO_DATE.test(input)
+    ? Promise.resolve(input)
+    : Promise.reject(usageError('Dates must be written as YYYY-MM-DD.')));
+/** An inclusive day range, both ends required. */
+export const periodFlags = {
+    'date-from': Flags.string({
+        description: 'First day of the period, inclusive (YYYY-MM-DD, in the app timezone)',
+        parse: dateParser,
+        required: true,
+    }),
+    'date-to': Flags.string({
+        description: 'Last day of the period, inclusive (YYYY-MM-DD, in the app timezone)',
+        parse: dateParser,
+        required: true,
+    }),
+};
+export const revenueBasisFlag = {
+    'revenue-basis': Flags.option({
+        description: 'Which revenue the revenue metrics use; the backend default applies when omitted',
+        options: revenueBases,
+    })(),
+};
+/** Where the period flags meet the sdk's field names. */
+export const periodParams = (flags) => ({ dateFrom: flags['date-from'], dateTo: flags['date-to'] });

package/dist/cli/base/attribution/index.d.ts

@@ -0,0 +1,4 @@
+export { AttributionCommand } from './attribution-command.js';
+export { build } from './build.js';
+export { periodFlags, periodParams, revenueBasisFlag } from './flags.js';
+export { openSession, resolveAttributionSession } from './openSession.js';

package/dist/cli/base/attribution/index.js

@@ -0,0 +1,4 @@
+export { AttributionCommand } from './attribution-command.js';
+export { build } from './build.js';
+export { periodFlags, periodParams, revenueBasisFlag } from './flags.js';
+export { openSession, resolveAttributionSession } from './openSession.js';

package/dist/cli/base/attribution/openSession.d.ts

@@ -0,0 +1,9 @@
+import type { ResolvedSession } from '../session.js';
+import type { Config } from '@oclif/core';
+/**
+ * The attribution backend takes the Adapty developer token, so the token, its source, the store and
+ * the user are the shared session as it is. Only the destination is this product's own:
+ * ADAPTY_ATTRIBUTION_API_URL, independent of ADAPTY_API_URL.
+ */
+export declare const resolveAttributionSession: (config: Config) => Promise<ResolvedSession>;
+export declare const openSession: (config: Config) => Promise<ResolvedSession>;

package/dist/cli/base/attribution/openSession.js

@@ -0,0 +1,19 @@
+import { DEFAULT_ATTRIBUTION_API_URL } from '../../../sdk/attribution/index.js';
+import { loadSession } from '../session.js';
+/**
+ * The attribution backend takes the Adapty developer token, so the token, its source, the store and
+ * the user are the shared session as it is. Only the destination is this product's own:
+ * ADAPTY_ATTRIBUTION_API_URL, independent of ADAPTY_API_URL.
+ */
+export const resolveAttributionSession = async (config) => ({
+    apiUrl: process.env.ADAPTY_ATTRIBUTION_API_URL ?? DEFAULT_ATTRIBUTION_API_URL,
+    ...await loadSession(config),
+});
+export const openSession = async (config) => {
+    const session = await resolveAttributionSession(config);
+    if (session.apiUrl !== DEFAULT_ATTRIBUTION_API_URL) {
+        // oclif's warn() is silent under --json; the destination warning must remain visible.
+        process.stderr.write(`Warning: Using non-default attribution API URL: ${session.apiUrl}\n`);
+    }
+    return session;
+};

package/dist/cli/base/base-command.d.ts

@@ -1,5 +1,12 @@
 import { Command } from '@oclif/core';
 import type { ErrorJson } from '../errors.js';
+import type { Config } from '@oclif/core';
+/** What a product's `build()` takes from the command that calls it. */
+export type CommandContext = {
+    config: Config;
+    signal: AbortSignal;
+    warn: (message: string) => void;
+};
 /**
  * What every command gets and nothing more: the output channel, cancellation, the single place
  * where sdk errors become CLI errors. Product SDKs and sessions belong to their adapters.

package/dist/cli/base/session.d.ts

@@ -0,0 +1,30 @@
+import type { SessionStore, SessionUser } from '../../sdk/core/session.js';
+import type { Config } from '@oclif/core';
+/**
+ * The CLI's world resolved into what the sdk asks for: where to talk, as whom, and where the
+ * session lives. Env vars are read in cli/base and only there — the sdk never touches process.env,
+ * which is what lets the same product code run under an MCP server.
+ */
+export type ResolvedSession = {
+    apiUrl: string;
+    /**
+     * Where the token came from. With ADAPTY_TOKEN in play, "no token in the file" and "not
+     * authenticated" are different answers, and `auth status` has to say which one it means.
+     */
+    source: 'env' | 'file' | 'none';
+    /** The store itself, not its path: `auth login`/`logout` write through it. */
+    store: SessionStore;
+    token?: string | undefined;
+    user?: SessionUser | undefined;
+};
+/** What a product command holds once it has demanded the token. */
+export type AuthenticatedSession = ResolvedSession & {
+    token: string;
+};
+/**
+ * Every product takes the same Adapty developer token, so as whom and where the session lives are
+ * resolved once, here. Where to talk is each product's own: its adapter adds `apiUrl`.
+ *
+ * ADAPTY_TOKEN wins over the stored session, as the published CLI already does.
+ */
+export declare const loadSession: (config: Config) => Promise<Omit<ResolvedSession, "apiUrl">>;

package/dist/cli/base/session.js

@@ -0,0 +1,20 @@
+import { createFileSessionStore } from '../../sdk/core/session.js';
+/**
+ * Every product takes the same Adapty developer token, so as whom and where the session lives are
+ * resolved once, here. Where to talk is each product's own: its adapter adds `apiUrl`.
+ *
+ * ADAPTY_TOKEN wins over the stored session, as the published CLI already does.
+ */
+export const loadSession = async (config) => {
+    // oclif's configDir already knows XDG on unix and LOCALAPPDATA on Windows
+    const store = createFileSessionStore(config.configDir);
+    const envToken = process.env.ADAPTY_TOKEN;
+    if (envToken !== undefined && envToken !== '') {
+        return { source: 'env', store, token: envToken };
+    }
+    const stored = await store.load();
+    if (stored === undefined) {
+        return { source: 'none', store };
+    }
+    return { source: 'file', store, token: stored.token, user: stored.user };
+};

package/dist/cli/commands/attribution/dimensions.d.ts

@@ -0,0 +1,7 @@
+import { AttributionCommand } from '../../base/attribution/index.js';
+import type { DimensionsResponse } from '../../../sdk/attribution/index.js';
+export default class AttributionDimensions extends AttributionCommand {
+    static description: string;
+    static examples: string[];
+    run(): Promise<DimensionsResponse>;
+}

package/dist/cli/commands/attribution/dimensions.js

@@ -0,0 +1,18 @@
+import { AttributionCommand } from '../../base/attribution/index.js';
+const describeDimension = (dimension) => {
+    const uses = [dimension.groupable ? 'group' : undefined, dimension.filterable ? 'filter' : undefined]
+        .filter(use => use !== undefined);
+    const granularities = dimension.granularities === null ? '' : `; granularities ${dimension.granularities.join(', ')}`;
+    // identity says what a filter takes: an entity id, or the value itself
+    return `${dimension.name}: ${dimension.label} (${uses.join(', ') || 'no use'}; identity ${dimension.identity}${granularities})`;
+};
+export default class AttributionDimensions extends AttributionCommand {
+    static description = 'List the dimensions an attribution report can group or filter by (not scoped to an app)';
+    static examples = ['<%= config.bin %> attribution dimensions', '<%= config.bin %> attribution dimensions --json'];
+    async run() {
+        await this.parse(AttributionDimensions);
+        const catalog = await this.attribution.dimensions();
+        this.render(catalog, ({ data }) => data.dimensions.map(dimension => describeDimension(dimension)).join('\n'));
+        return catalog;
+    }
+}

package/dist/cli/commands/attribution/metrics.d.ts

@@ -0,0 +1,7 @@
+import { AttributionCommand } from '../../base/attribution/index.js';
+import type { MetricsResponse } from '../../../sdk/attribution/index.js';
+export default class AttributionMetrics extends AttributionCommand {
+    static description: string;
+    static examples: string[];
+    run(): Promise<MetricsResponse>;
+}

package/dist/cli/commands/attribution/metrics.js

@@ -0,0 +1,35 @@
+import { AttributionCommand } from '../../base/attribution/index.js';
+/** Traits under their catalog field names, so a reader knows what to look for in --json. */
+const describeMetric = (metric) => {
+    const traits = [
+        metric.unit,
+        metric.spend_based ? 'spend_based' : undefined,
+        metric.denominator === null ? undefined : `denominator ${metric.denominator.join(' + ')}`,
+    ].filter(trait => trait !== undefined);
+    const pattern = metric.pattern === null
+        ? ''
+        : ` — pattern ${metric.pattern}${metric.example === null ? '' : `, e.g. ${metric.example}`}`;
+    return `${metric.name} (${traits.join(', ')})${pattern}\n  ${metric.label}: ${metric.description}`;
+};
+const describeLimits = (limits) => {
+    const windows = Object.entries(limits.max_window_days)
+        .map(([grouping, days]) => `${grouping.replaceAll('_', ' ')} ${days}`)
+        .join(', ');
+    return [
+        `Limits: ${limits.max_metrics} metrics, ${limits.max_filter_values} values per filter, `
+            + `${limits.max_keyword_length} characters per keyword, ${limits.max_rows} rows`,
+        `  Widest period in days: ${windows}`,
+        `  Predictions: ${limits.max_prediction_horizons} horizons, day ${limits.max_prediction_day} at most, `
+            + `${limits.max_prediction_non_date_dimensions} dimensions besides date`,
+    ].join('\n');
+};
+export default class AttributionMetrics extends AttributionCommand {
+    static description = 'List the metrics an attribution report can ask for (not scoped to an app)';
+    static examples = ['<%= config.bin %> attribution metrics', '<%= config.bin %> attribution metrics --json'];
+    async run() {
+        await this.parse(AttributionMetrics);
+        const catalog = await this.attribution.metrics();
+        this.render(catalog, ({ data }) => [...data.metrics.map(metric => describeMetric(metric)), '', describeLimits(data.limits)].join('\n'));
+        return catalog;
+    }
+}

package/dist/cli/commands/attribution/report/index.d.ts

@@ -0,0 +1,18 @@
+import { AttributionCommand } from '../../../base/attribution/index.js';
+import type { ReportFilter, ReportResponse, ReportSort } from '../../../../sdk/attribution/index.js';
+export default class AttributionReport extends AttributionCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        sort: import("@oclif/core/interfaces").OptionFlag<ReportSort | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'revenue-basis': import("@oclif/core/interfaces").OptionFlag<"gross" | "proceeds" | "net" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        metrics: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+        'group-by': import("@oclif/core/interfaces").OptionFlag<("store" | "date" | "campaign" | "adset" | "ad" | "keyword" | "channel" | "country")[], import("@oclif/core/interfaces").CustomOptions>;
+        granularity: import("@oclif/core/interfaces").OptionFlag<"day" | "week" | "month" | "quarter" | "year" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        filter: import("@oclif/core/interfaces").OptionFlag<ReportFilter[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'date-from': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'date-to': 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<ReportResponse>;
+}

package/dist/cli/commands/attribution/report/index.js

@@ -0,0 +1,93 @@
+import { Flags } from '@oclif/core';
+import { granularities, reportGroupBy, sortDirections, validateReport } from '../../../../sdk/attribution/index.js';
+import { assertValid } from '../../../../sdk/core/validation.js';
+import { AttributionCommand, periodFlags, periodParams, revenueBasisFlag } from '../../../base/attribution/index.js';
+import { usageError } from '../../../errors.js';
+import { appIdFlag } from '../../../flags.js';
+import { renderReport } from './lib/render.js';
+/** A comma not preceded by a backslash: `\,` keeps a comma inside a value, as oclif's own delimiter does. */
+const VALUE_SEPARATOR = /(?<!\\),/;
+/** `dimension=value[,value]`: one value filters by equality, several by any of them. */
+const parseFilter = (input) => {
+    const separator = input.indexOf('=');
+    const dimension = separator === -1 ? '' : input.slice(0, separator).trim();
+    const values = separator === -1
+        ? []
+        : input.slice(separator + 1).split(VALUE_SEPARATOR).map(value => value.replaceAll('\\,', ',').trim())
+            .filter(value => value !== '');
+    return dimension === '' || values.length === 0
+        ? Promise.reject(usageError(`Expected dimension=value[,value], got "${input}".`))
+        : Promise.resolve({ dimension, values });
+};
+const isDirection = (value) => sortDirections.includes(value);
+/** `field[:asc|desc]`, ascending when the direction is left out. */
+const parseSort = (input) => {
+    const separator = input.lastIndexOf(':');
+    const field = (separator === -1 ? input : input.slice(0, separator)).trim();
+    const direction = separator === -1 ? 'asc' : input.slice(separator + 1).trim();
+    if (field === '') {
+        return Promise.reject(usageError(`Expected field[:asc|desc], got "${input}".`));
+    }
+    return isDirection(direction)
+        ? Promise.resolve({ direction, field })
+        : Promise.reject(usageError(`The sort direction must be asc or desc, got "${direction}".`));
+};
+export default class AttributionReport extends AttributionCommand {
+    static description = 'Run an Attribution report for an app: metrics over a period, grouped by dimensions';
+    static examples = [
+        '<%= config.bin %> attribution report --app APP_UUID --date-from 2026-08-01 --date-to 2026-08-31 --metrics spend,installs,d7_roas --group-by campaign',
+        '<%= config.bin %> attribution report --app APP_UUID --date-from 2026-08-01 --date-to 2026-08-31 --metrics spend --group-by date --granularity week --filter country=US,GB --sort spend:desc',
+        '<%= config.bin %> attribution report --app APP_UUID --date-from 2026-08-01 --date-to 2026-08-31 --metrics spend,installs,d7_roas --group-by campaign --json',
+    ];
+    // Input shape here; the rules (dates in order, a granularity exactly when grouping by date) live
+    // in sdk/attribution/report.ts, and which names exist is the backend catalog's knowledge.
+    static flags = {
+        ...appIdFlag,
+        ...periodFlags,
+        'metrics': Flags.string({
+            delimiter: ',',
+            description: 'Metric names, as `adapty attribution metrics` lists them (repeatable or comma-separated)',
+            multiple: true,
+            required: true,
+        }),
+        'group-by': Flags.option({
+            delimiter: ',',
+            description: 'Dimensions to group rows by (repeatable or comma-separated)',
+            multiple: true,
+            options: reportGroupBy,
+            required: true,
+        })(),
+        'granularity': Flags.option({
+            description: 'Date bucket; required with --group-by date, and allowed only with it',
+            options: granularities,
+        })(),
+        'filter': Flags.custom({
+            description: 'Keep rows whose dimension has one of the values: dimension=value[,value] (repeatable; `\\,` for a comma inside a value)',
+            multiple: true,
+            parse: parseFilter,
+        })(),
+        ...revenueBasisFlag,
+        'sort': Flags.custom({
+            description: 'Sort rows by a requested metric or dimension: field[:asc|desc] (ascending by default)',
+            parse: parseSort,
+        })(),
+    };
+    async run() {
+        const { flags } = await this.parse(AttributionReport);
+        const input = {
+            appId: flags.app,
+            ...periodParams(flags),
+            filters: flags.filter,
+            granularity: flags.granularity,
+            groupBy: flags['group-by'],
+            metrics: flags.metrics.filter(metric => metric !== ''),
+            revenueBasis: flags['revenue-basis'],
+            sort: flags.sort,
+        };
+        // Before this.attribution: bad input is exit 2 even without a token
+        assertValid(validateReport(input));
+        const report = await this.attribution.report(input);
+        this.render(report, renderReport);
+        return report;
+    }
+}

package/dist/cli/commands/attribution/report/lib/render.d.ts

@@ -0,0 +1,3 @@
+import type { ReportResponse } from '../../../../../sdk/attribution/index.js';
+/** Private to `attribution report`: one labelled block per row, `---` between rows, then the totals. */
+export declare const renderReport: (report: ReportResponse) => string;

package/dist/cli/commands/attribution/report/lib/render.js

@@ -0,0 +1,24 @@
+/** A metric the backend could not compute is null, and printing it as 0 would be a lie. */
+const NOT_COMPUTED = '—';
+const formatValue = (value) => {
+    if (value === null || value === undefined) {
+        return NOT_COMPUTED;
+    }
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    return JSON.stringify(value);
+};
+/**
+ * Field names stay as the server sends them: they are the names `--metrics`, `--group-by`, `--filter`
+ * and `--sort` take, so what a reader sees is what they can type next.
+ */
+const block = (record) => Object.entries(record).map(([name, value]) => `${name}: ${formatValue(value)}`);
+/** Private to `attribution report`: one labelled block per row, `---` between rows, then the totals. */
+export const renderReport = (report) => {
+    const { rows, totals } = report.data;
+    const body = rows.length === 0
+        ? 'No rows for this period.'
+        : rows.map(row => block(row).join('\n')).join('\n---\n');
+    return totals === null ? body : `${body}\n\n${['Totals', ...block(totals)].join('\n')}`;
+};

package/dist/cli/commands/attribution/values.d.ts

@@ -0,0 +1,14 @@
+import { AttributionCommand } from '../../base/attribution/index.js';
+import type { ValuesResponse } from '../../../sdk/attribution/index.js';
+export default class AttributionValues extends AttributionCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'revenue-basis': import("@oclif/core/interfaces").OptionFlag<"gross" | "proceeds" | "net" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        dimension: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'date-from': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'date-to': 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<ValuesResponse>;
+}