@mirage-cli/dataforseo-cli 0.1.0

package/dist/framework/index.d.ts

@@ -0,0 +1,2 @@
+export { CommandSpec, IOResult, Operand, OperandKind, Option, ParsedArgs, type ByteSource, type CommandSpecInit, type IOResultInit, type OperandInit, type OptionInit, type ParsedArgsInit, } from "./types.ts";
+export { argvToInput, command, group, invoke, mountGroup, ok, toCommander, type CommandDef, type CommandDefInit, type CommandFn, type CommandFnResult, type CommandGroup, type CommandOpts, type InvokeInput, type InvokeResult, } from "./runtime.ts";

package/dist/framework/output.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared option mixins (`OUTPUT_OPTIONS`, `LOC_LANG_OPTIONS`) and the
+ * `applyOutput()` helper that every data command uses to render its
+ * DfsResponse into bytes + IOResult per the user's --output/--columns/etc.
+ */
+import type { DfsResponse } from "../lib/client.ts";
+import type { CommandFnResult, CommandOpts } from "./runtime.ts";
+import { Operand, Option } from "./types.ts";
+export declare const OUTPUT_OPTIONS: readonly Option[];
+export declare function applyOutput(resp: DfsResponse, opts: CommandOpts): CommandFnResult;
+export declare const LOC_LANG_OPTIONS: readonly Option[];
+export interface LocLangResolved {
+    locationName?: string;
+    locationCode?: number;
+    languageName?: string;
+    languageCode?: string;
+}
+export declare function resolveLocLang(opts: CommandOpts): LocLangResolved;
+export declare function textOp(name: string, opts?: {
+    variadic?: boolean;
+    required?: boolean;
+}): Operand;
+export declare function flagStr(opts: CommandOpts, key: string, fallback?: string): string;
+export declare function flagBool(opts: CommandOpts, key: string): boolean;
+export declare function flagNum(opts: CommandOpts, key: string, fallback: number): number;

package/dist/framework/runtime.d.ts

@@ -0,0 +1,74 @@
+import { Command } from "commander";
+import { CommandSpec, IOResult, type ByteSource } from "./types.ts";
+/**
+ * Mirage-compatible command function signature: (accessor, paths, texts, opts).
+ * We use loose accessor/opts types since CLI commands typically don't touch
+ * either. When registered into a real mirage workspace, mirage supplies the
+ * concrete Accessor and CommandOpts.
+ */
+export type CommandOpts = {
+    flags: Record<string, string | boolean>;
+    stdin?: ByteSource | null;
+    cwd?: string;
+    resource?: unknown;
+    [k: string]: unknown;
+};
+export type CommandFnResult = [ByteSource | null, IOResult] | null;
+export type CommandFn = (accessor: unknown, paths: readonly string[], texts: readonly string[], opts: CommandOpts) => Promise<CommandFnResult> | CommandFnResult;
+export interface CommandDefInit {
+    name: string;
+    /** Mirage's command() requires a resource ("ram", "s3", etc.) or null for general. */
+    resource?: string | string[] | null;
+    spec: CommandSpec;
+    fn: CommandFn;
+    /** Optional sugar — used if `spec.description` is null. */
+    description?: string;
+}
+export interface CommandDef {
+    readonly name: string;
+    readonly resource: string | string[] | null;
+    readonly spec: CommandSpec;
+    readonly fn: CommandFn;
+    readonly description: string | null;
+}
+/** Author a command. Same shape as @struktoai/mirage-core's `command()`. */
+export declare function command(init: CommandDefInit): CommandDef;
+/** Group commands under a namespace (CLI nesting). Mirage doesn't care about groups. */
+export interface CommandGroup {
+    readonly name: string;
+    readonly description: string | null;
+    readonly commands: readonly CommandDef[];
+    readonly groups: readonly CommandGroup[];
+}
+export declare function group(init: {
+    name: string;
+    description?: string;
+    commands?: readonly CommandDef[];
+    groups?: readonly CommandGroup[];
+}): CommandGroup;
+export interface InvokeInput {
+    paths?: readonly string[];
+    texts?: readonly string[];
+    flags?: Record<string, string | boolean>;
+    stdin?: ByteSource | null;
+}
+export interface InvokeResult {
+    bytes: Uint8Array;
+    text: string;
+    result: IOResult;
+}
+/** Programmatically invoke a command. Pass argv tokens or a structured input. */
+export declare function invoke(cmd: CommandDef, input?: InvokeInput | readonly string[]): Promise<InvokeResult>;
+export declare function argvToInput(spec: CommandSpec, argv: readonly string[]): InvokeInput;
+export declare function toCommander(cmd: CommandDef): Command;
+export declare function mountGroup(parent: Command, g: CommandGroup): Command;
+/**
+ * Convenience for command authors: wrap text/bytes as a CommandFnResult.
+ *
+ * `ok("hello")` → stdout="hello", exitCode=0
+ * `ok(bytes, { exitCode: 1, stderr: "oops" })`
+ */
+export declare function ok(body: string | Uint8Array, init?: {
+    exitCode?: number;
+    stderr?: string | Uint8Array;
+}): CommandFnResult;

package/dist/framework/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Runtime classes that match @struktoai/mirage-core's shapes exactly, plus
+ * a thin CLI-only extension (defaultValue, required, name, variadic) carried
+ * on Option/Operand for commander adapter convenience.
+ *
+ * Type-only import from mirage-core: zero runtime dep, zero bundle bytes from
+ * mirage; tsc enforces structural parity (mirage-side change → tsc error here).
+ */
+import type { Option as MOption, Operand as MOperand, CommandSpec as MCommandSpec, ParsedArgs as MParsedArgs, OptionInit as MOptionInit, OperandInit as MOperandInit, CommandSpecInit as MCommandSpecInit, ParsedArgsInit as MParsedArgsInit, IOResultInit as MIOResultInit, OperandKind as MOperandKind, ByteSource } from "@struktoai/mirage-core";
+export type { ByteSource };
+export type OperandKind = MOperandKind;
+export declare const OperandKind: Readonly<{
+    NONE: "none";
+    PATH: "path";
+    TEXT: "text";
+}>;
+/** Our CLI-extended OptionInit: mirage's fields + `defaultValue` and `required` for commander. */
+export interface OptionInit extends MOptionInit {
+    defaultValue?: string | boolean | null;
+    required?: boolean;
+}
+export declare class Option implements MOption {
+    readonly short: string | null;
+    readonly long: string | null;
+    readonly valueKind: OperandKind;
+    readonly numericShorthand: boolean;
+    readonly description: string | null;
+    readonly defaultValue: string | boolean | null;
+    readonly required: boolean;
+    constructor(init?: OptionInit);
+    /** Stable identifier (kebab-case) for opts.flags lookup. */
+    get name(): string;
+}
+/** Our CLI-extended OperandInit: mirage has only `kind`; we add `name`/`variadic`/`required`. */
+export interface OperandInit extends MOperandInit {
+    name?: string;
+    variadic?: boolean;
+    required?: boolean;
+}
+export declare class Operand implements MOperand {
+    readonly kind: OperandKind;
+    readonly name: string;
+    readonly variadic: boolean;
+    readonly required: boolean;
+    constructor(init?: OperandInit);
+}
+export type CommandSpecInit = MCommandSpecInit;
+export declare class CommandSpec implements MCommandSpec {
+    readonly options: readonly Option[];
+    readonly positional: readonly Operand[];
+    readonly rest: Operand | null;
+    readonly ignoreTokens: ReadonlySet<string>;
+    readonly description: string | null;
+    constructor(init?: CommandSpecInit);
+}
+export type ParsedArgsInit = MParsedArgsInit;
+export declare class ParsedArgs implements MParsedArgs {
+    readonly flags: Record<string, string | boolean>;
+    readonly args: [string, OperandKind][];
+    readonly cachePaths: string[];
+    readonly pathFlagValues: string[];
+    constructor(init: ParsedArgsInit);
+    paths(): string[];
+    routingPaths(): string[];
+    texts(): string[];
+    flag(name: string, fallback?: string | boolean | null): string | boolean | null;
+}
+/**
+ * IOResult — partial implementation of mirage's class. We populate stdout /
+ * stderr / exitCode; the streaming/reads/writes/cache surface is left at
+ * defaults. Mirage uses these structurally, so missing methods are fine for
+ * simple command outputs (we don't stream).
+ */
+export interface IOResultInit extends Omit<MIOResultInit, "stdout" | "stderr"> {
+    /** Accepts either bytes or a UTF-8 string (auto-encoded). */
+    stdout?: ByteSource | string | null;
+    /** Accepts either bytes or a UTF-8 string (auto-encoded). */
+    stderr?: ByteSource | string | null;
+}
+export declare class IOResult {
+    stdout: Uint8Array | null;
+    stderr: Uint8Array | null;
+    exitCode: number;
+    reads: Record<string, ByteSource>;
+    writes: Record<string, ByteSource>;
+    cache: string[];
+    streamSource: IOResult | null;
+    constructor(init?: IOResultInit);
+}

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Library entry point. Three layers:
+ *
+ * 1. Pure async API functions  — `keywordsSearchVolume`, `serpGoogleOrganic`, etc.
+ *    Call them directly when you just need a `DfsResponse`.
+ *
+ * 2. Mirage-shaped command definitions — `keywordsSearchVolumeCmd`, etc.
+ *    Built with the local `command()` factory, whose `CommandSpec` / `Option` /
+ *    `Operand` / `OperandKind` / `IOResult` shapes match @struktoai/mirage-browser.
+ *    Use `invoke(cmd, { texts, flags })` to run one programmatically, or
+ *    `toCommander(cmd)` to mount it onto your own commander program.
+ *
+ * 3. `buildProgram(): Command` — a fully-assembled Commander program (same one
+ *    the `dfs` CLI binary uses). For in-process wrappers like
+ *    `@mirage-cli/dataforseo`.
+ *
+ * The CLI binary in `dist/dfs.js` is built from these same definitions.
+ */
+export { buildProgram } from "./dfs.ts";
+export { CommandSpec, IOResult, Operand, OperandKind, Option, ParsedArgs, argvToInput, command, group, invoke, mountGroup, ok, toCommander, type ByteSource, type CommandDef, type CommandDefInit, type CommandFn, type CommandFnResult, type CommandGroup, type CommandOpts, type CommandSpecInit, type IOResultInit, type InvokeInput, type InvokeResult, type OperandInit, type OptionInit, type ParsedArgsInit, } from "./framework/index.ts";
+export { applyOutput, flagBool, flagNum, flagStr, LOC_LANG_OPTIONS, OUTPUT_OPTIONS, resolveLocLang, textOp, type LocLangResolved, } from "./framework/output.ts";
+export { call, extractItems, get, type CallOptions, type DfsResponse, } from "./lib/client.ts";
+export { loadCredentials, saveCredentials, basicAuthHeader, configPath, type Credentials } from "./lib/auth.ts";
+export { findEndpoint, loadEndpoints, searchEndpoints, type EndpointInfo, type EndpointMethod } from "./lib/spec.ts";
+export { render, type OutputFormat, type RenderOptions } from "./lib/output.ts";
+export { keywordsIdeas, keywordsRanked, keywordsSearchVolume, keywordsSuggestions, type LocLang, } from "./api/keywords.ts";
+export { serpGoogleImages, serpGoogleMaps, serpGoogleNews, serpGoogleOrganic, serpYoutubeOrganic, type SerpOpts, } from "./api/serp.ts";
+export { backlinksAnchors, backlinksCompetitors, backlinksList, backlinksRanks, backlinksReferringDomains, backlinksSummary, } from "./api/backlinks.ts";
+export { labsBulkDifficulty, labsCompetitors, labsHistorical, labsIntent, labsIntersection, labsKeywordOverview, labsOverview, labsRelated, labsTopSearches, } from "./api/labs.ts";
+export { aiAsk, aiMentionMetrics, aiMentions, aiSearchVolume, aiTopDomains, aiTopPages, type AiModel, } from "./api/ai.ts";
+export { trendsDemography, trendsExplore, trendsSubregion, type TrendsType } from "./api/trends.ts";
+export { listLanguages, listLocations, userData } from "./api/meta.ts";
+export { keywordsGroup, keywordsIdeasCmd, keywordsRankedCmd, keywordsSearchVolumeCmd, keywordsSuggestionsCmd, } from "./commands/keywords.ts";
+export { serpGroup, serpGoogleImagesCmd, serpGoogleMapsCmd, serpGoogleNewsCmd, serpGoogleOrganicCmd, serpYoutubeOrganicCmd, } from "./commands/serp.ts";
+export { backlinksAnchorsCmd, backlinksCompetitorsCmd, backlinksGroup, backlinksListCmd, backlinksRanksCmd, backlinksReferringDomainsCmd, backlinksSummaryCmd, } from "./commands/backlinks.ts";
+export { labsBulkDifficultyCmd, labsCompetitorsCmd, labsGroup, labsHistoricalCmd, labsIntentCmd, labsIntersectionCmd, labsKeywordOverviewCmd, labsOverviewCmd, labsRelatedCmd, labsTopSearchesCmd, } from "./commands/labs.ts";
+export { aiAskCmd, aiGroup, aiMentionsCmd, aiMetricsCmd, aiSearchVolumeCmd, aiTopDomainsCmd, aiTopPagesCmd, } from "./commands/ai.ts";
+export { trendsDemographyCmd, trendsExploreCmd, trendsGroup, trendsSubregionCmd, } from "./commands/trends.ts";
+export { languagesCmd, locationsCmd, userCmd } from "./commands/meta.ts";
+export { loginCmd, whoamiCmd } from "./commands/login.ts";
+export { rawCmd } from "./commands/raw.ts";
+export { endpointsGroup, endpointsListCmd, endpointsShowCmd, endpointsTagsCmd } from "./commands/endpoints.ts";