@qontoctl/core 0.0.0 → 0.1.0

package/README.md

@@ -0,0 +1,93 @@
+# @qontoctl/core
+
+[![npm version](https://img.shields.io/npm/v/@qontoctl/core?logo=npm)](https://www.npmjs.com/package/@qontoctl/core)
+
+Core library for [Qonto](https://qonto.com) API integration — HTTP client, authentication, configuration, and typed service functions.
+
+Part of the [QontoCtl](https://github.com/alexey-pelykh/qontoctl) project.
+
+## Installation
+
+```sh
+npm install @qontoctl/core
+```
+
+## Usage
+
+```ts
+import { resolveConfig, buildApiKeyAuthorization, HttpClient, getOrganization } from "@qontoctl/core";
+
+// Resolve configuration from file or environment
+const { config, endpoint } = await resolveConfig();
+
+// Build authorization headers
+const authorization = buildApiKeyAuthorization(config.apiKey);
+
+// Create an HTTP client
+const client = new HttpClient({ baseUrl: endpoint, authorization });
+
+// Fetch organization details
+const org = await getOrganization(client);
+```
+
+## API
+
+### Configuration
+
+- **`resolveConfig(options?): Promise<ConfigResult>`** — resolve credentials from config files and environment variables. Returns `{ config, endpoint, warnings }`.
+- **`loadConfigFile(path)`** — load a YAML configuration file
+- **`validateConfig(config)`** — validate configuration structure
+- **`applyEnvOverlay(config, prefix?)`** — overlay environment variable overrides
+- **`ConfigError`** — error thrown on configuration validation failures or missing credentials
+
+### Authentication
+
+- **`buildApiKeyAuthorization(credentials)`** — build authorization headers from API key credentials
+- **`AuthError`** — error thrown when API key credentials are missing or invalid
+
+### HTTP Client
+
+- **`HttpClient`** — HTTP client for the Qonto API with rate-limit handling
+- **`QontoApiError`** — typed error for Qonto API error responses
+- **`QontoRateLimitError`** — error for rate-limit (429) responses
+
+### Constants
+
+- **`API_BASE_URL`** — production API base URL (`https://thirdparty.qonto.com`)
+- **`SANDBOX_BASE_URL`** — sandbox API base URL (`https://thirdparty-sandbox.staging.qonto.co`)
+
+### Services
+
+- **`getOrganization(client)`** — fetch organization details
+- **`getBankAccount(client, id)`** — fetch a bank account by ID
+- **`getTransaction(client, id)`** — fetch a transaction by ID
+- **`buildTransactionQueryParams(params)`** — build query parameters for transaction listing
+
+### Types
+
+- `Organization`, `BankAccount`, `Transaction`, `TransactionLabel`
+- `Label`, `Membership`, `Statement`, `StatementFile`
+- `QontoctlConfig`, `ApiKeyCredentials`, `ListTransactionsParams`
+- `ConfigResult`, `ResolveOptions`, `LoadResult`, `ValidationResult`
+- `HttpClientOptions`, `HttpClientLogger`, `QueryParams`, `QueryParamValue`, `QontoApiErrorEntry`
+
+## Configuration Resolution
+
+QontoCtl resolves credentials in this order:
+
+1. `QONTOCTL_*` environment variables (highest priority)
+2. `.qontoctl.yaml` in the current directory
+3. `~/.qontoctl.yaml` (home default)
+
+With `--profile <name>`:
+
+1. `QONTOCTL_<NAME>_*` environment variables
+2. `~/.qontoctl/<name>.yaml`
+
+## Requirements
+
+- Node.js >= 24
+
+## License
+
+[AGPL-3.0-only](https://github.com/alexey-pelykh/qontoctl/blob/main/LICENSE) — For commercial licensing, contact the maintainer.

package/dist/api-types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A bank account as returned by the Qonto API.
+ */
+export interface BankAccount {
+    readonly id: string;
+    readonly name: string;
+    readonly status: string;
+    readonly main: boolean;
+    readonly organization_id: string;
+    readonly iban: string;
+    readonly bic: string;
+    readonly currency: string;
+    readonly balance: number;
+    readonly balance_cents: number;
+    readonly authorized_balance: number;
+    readonly authorized_balance_cents: number;
+    readonly slug: string;
+}
+/**
+ * Organization details as returned by `GET /v2/organization`.
+ */
+export interface Organization {
+    readonly slug: string;
+    readonly legal_name: string;
+    readonly bank_accounts: readonly BankAccount[];
+}
+/**
+ * Pagination metadata returned by the Qonto API.
+ */
+export interface PaginationMeta {
+    readonly current_page: number;
+    readonly next_page: number | null;
+    readonly prev_page: number | null;
+    readonly total_pages: number;
+    readonly total_count: number;
+    readonly per_page: number;
+}
+//# sourceMappingURL=api-types.d.ts.map

package/dist/api-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-types.d.ts","sourceRoot":"","sources":["../src/api-types.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,SAAS,WAAW,EAAE,CAAC;CAChD;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B"}

package/dist/api-types.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+export {};
+//# sourceMappingURL=api-types.js.map

package/dist/api-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-types.js","sourceRoot":"","sources":["../src/api-types.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC"}

package/dist/auth/api-key.d.ts

@@ -0,0 +1,16 @@
+import type { ApiKeyCredentials } from "../config/types.js";
+/**
+ * Error thrown when API key authentication fails due to missing or invalid credentials.
+ */
+export declare class AuthError extends Error {
+    constructor(message: string);
+}
+/**
+ * Builds the Authorization header value from API key credentials.
+ *
+ * The Qonto API uses a simple `{slug}:{key}` format (no Base64 encoding).
+ *
+ * @throws {AuthError} when credentials are missing or incomplete
+ */
+export declare function buildApiKeyAuthorization(credentials: ApiKeyCredentials): string;
+//# sourceMappingURL=api-key.d.ts.map

package/dist/auth/api-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.d.ts","sourceRoot":"","sources":["../../src/auth/api-key.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;GAEG;AACH,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,iBAAiB,GAAG,MAAM,CAU/E"}

package/dist/auth/api-key.js

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+/**
+ * Error thrown when API key authentication fails due to missing or invalid credentials.
+ */
+export class AuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AuthError";
+    }
+}
+/**
+ * Builds the Authorization header value from API key credentials.
+ *
+ * The Qonto API uses a simple `{slug}:{key}` format (no Base64 encoding).
+ *
+ * @throws {AuthError} when credentials are missing or incomplete
+ */
+export function buildApiKeyAuthorization(credentials) {
+    if (credentials.organizationSlug === "") {
+        throw new AuthError("Missing organization slug in API key credentials");
+    }
+    if (credentials.secretKey === "") {
+        throw new AuthError("Missing secret key in API key credentials");
+    }
+    return `${credentials.organizationSlug}:${credentials.secretKey}`;
+}
+//# sourceMappingURL=api-key.js.map

package/dist/auth/api-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.js","sourceRoot":"","sources":["../../src/auth/api-key.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAIpC;;GAEG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAC,WAA8B;IACrE,IAAI,WAAW,CAAC,gBAAgB,KAAK,EAAE,EAAE,CAAC;QACxC,MAAM,IAAI,SAAS,CAAC,kDAAkD,CAAC,CAAC;IAC1E,CAAC;IAED,IAAI,WAAW,CAAC,SAAS,KAAK,EAAE,EAAE,CAAC;QACjC,MAAM,IAAI,SAAS,CAAC,2CAA2C,CAAC,CAAC;IACnE,CAAC;IAED,OAAO,GAAG,WAAW,CAAC,gBAAgB,IAAI,WAAW,CAAC,SAAS,EAAE,CAAC;AACpE,CAAC"}

package/dist/auth/index.d.ts

@@ -0,0 +1,2 @@
+export { AuthError, buildApiKeyAuthorization } from "./api-key.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC"}

package/dist/auth/index.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+export { AuthError, buildApiKeyAuthorization } from "./api-key.js";
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,SAAS,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC"}

package/dist/config/env.d.ts

@@ -0,0 +1,17 @@
+import type { QontoctlConfig } from "./types.js";
+/**
+ * Overlays environment variables onto a config.
+ *
+ * - Without profile: reads `QONTOCTL_ORGANIZATION_SLUG`, `QONTOCTL_SECRET_KEY`,
+ *   `QONTOCTL_ENDPOINT`, and `QONTOCTL_SANDBOX`
+ * - With profile: reads `QONTOCTL_{PROFILE}_ORGANIZATION_SLUG`,
+ *   `QONTOCTL_{PROFILE}_SECRET_KEY`, `QONTOCTL_{PROFILE}_ENDPOINT`, and
+ *   `QONTOCTL_{PROFILE}_SANDBOX` (profile name uppercased, hyphens→underscores)
+ *
+ * Env vars take precedence over file values.
+ */
+export declare function applyEnvOverlay(config: QontoctlConfig, options?: {
+    profile?: string | undefined;
+    env?: Record<string, string | undefined> | undefined;
+}): QontoctlConfig;
+//# sourceMappingURL=env.d.ts.map

package/dist/config/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAQjD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE;IACR,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;CACtD,GACA,cAAc,CA+BhB"}

package/dist/config/env.js

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+const ENV_PREFIX = "QONTOCTL";
+const ORG_SLUG_SUFFIX = "ORGANIZATION_SLUG";
+const SECRET_KEY_SUFFIX = "SECRET_KEY";
+const ENDPOINT_SUFFIX = "ENDPOINT";
+const SANDBOX_SUFFIX = "SANDBOX";
+/**
+ * Overlays environment variables onto a config.
+ *
+ * - Without profile: reads `QONTOCTL_ORGANIZATION_SLUG`, `QONTOCTL_SECRET_KEY`,
+ *   `QONTOCTL_ENDPOINT`, and `QONTOCTL_SANDBOX`
+ * - With profile: reads `QONTOCTL_{PROFILE}_ORGANIZATION_SLUG`,
+ *   `QONTOCTL_{PROFILE}_SECRET_KEY`, `QONTOCTL_{PROFILE}_ENDPOINT`, and
+ *   `QONTOCTL_{PROFILE}_SANDBOX` (profile name uppercased, hyphens→underscores)
+ *
+ * Env vars take precedence over file values.
+ */
+export function applyEnvOverlay(config, options) {
+    const env = options?.env ?? process.env;
+    const prefix = buildPrefix(options?.profile);
+    const orgSlug = env[`${prefix}_${ORG_SLUG_SUFFIX}`];
+    const secretKey = env[`${prefix}_${SECRET_KEY_SUFFIX}`];
+    const endpoint = env[`${prefix}_${ENDPOINT_SUFFIX}`];
+    const sandbox = env[`${prefix}_${SANDBOX_SUFFIX}`];
+    let result = config;
+    if (orgSlug !== undefined || secretKey !== undefined) {
+        const existing = result.apiKey;
+        result = {
+            ...result,
+            apiKey: {
+                organizationSlug: orgSlug ?? existing?.organizationSlug ?? "",
+                secretKey: secretKey ?? existing?.secretKey ?? "",
+            },
+        };
+    }
+    if (endpoint !== undefined) {
+        result = { ...result, endpoint };
+    }
+    if (sandbox !== undefined) {
+        result = { ...result, sandbox: sandbox === "1" || sandbox === "true" };
+    }
+    return result;
+}
+function buildPrefix(profile) {
+    if (profile === undefined) {
+        return ENV_PREFIX;
+    }
+    const normalized = profile.toUpperCase().replaceAll("-", "_");
+    return `${ENV_PREFIX}_${normalized}`;
+}
+//# sourceMappingURL=env.js.map

package/dist/config/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAIpC,MAAM,UAAU,GAAG,UAAU,CAAC;AAC9B,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAC5C,MAAM,iBAAiB,GAAG,YAAY,CAAC;AACvC,MAAM,eAAe,GAAG,UAAU,CAAC;AACnC,MAAM,cAAc,GAAG,SAAS,CAAC;AAEjC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAsB,EACtB,OAGC;IAED,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,IAAK,OAAO,CAAC,GAA0C,CAAC;IAChF,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAE7C,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,MAAM,IAAI,eAAe,EAAE,CAAC,CAAC;IACpD,MAAM,SAAS,GAAG,GAAG,CAAC,GAAG,MAAM,IAAI,iBAAiB,EAAE,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,MAAM,IAAI,eAAe,EAAE,CAAC,CAAC;IACrD,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,MAAM,IAAI,cAAc,EAAE,CAAC,CAAC;IAEnD,IAAI,MAAM,GAAG,MAAM,CAAC;IAEpB,IAAI,OAAO,KAAK,SAAS,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QACrD,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC;QAC/B,MAAM,GAAG;YACP,GAAG,MAAM;YACT,MAAM,EAAE;gBACN,gBAAgB,EAAE,OAAO,IAAI,QAAQ,EAAE,gBAAgB,IAAI,EAAE;gBAC7D,SAAS,EAAE,SAAS,IAAI,QAAQ,EAAE,SAAS,IAAI,EAAE;aAClD;SACF,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,GAAG,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnC,CAAC;IAED,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,GAAG,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;IACzE,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,WAAW,CAAC,OAA2B;IAC9C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,MAAM,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC9D,OAAO,GAAG,UAAU,IAAI,UAAU,EAAE,CAAC;AACvC,CAAC"}

package/dist/config/index.d.ts

@@ -0,0 +1,8 @@
+export type { ApiKeyCredentials, QontoctlConfig, ConfigResult, ResolveOptions } from "./types.js";
+export { resolveConfig, ConfigError } from "./resolve.js";
+export { loadConfigFile } from "./loader.js";
+export type { LoadResult } from "./loader.js";
+export { isValidProfileName, validateConfig } from "./validate.js";
+export type { ValidationResult } from "./validate.js";
+export { applyEnvOverlay } from "./env.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAClG,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACnE,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC"}

package/dist/config/index.js

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+export { resolveConfig, ConfigError } from "./resolve.js";
+export { loadConfigFile } from "./loader.js";
+export { isValidProfileName, validateConfig } from "./validate.js";
+export { applyEnvOverlay } from "./env.js";
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAGpC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEnE,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC"}

package/dist/config/loader.d.ts

@@ -0,0 +1,18 @@
+export interface LoadResult {
+    /** Parsed YAML content, or `undefined` if no file was found. */
+    raw: unknown;
+    /** Path of the file that was loaded, or `undefined` if none found. */
+    path: string | undefined;
+}
+/**
+ * Resolves and loads the appropriate config file.
+ *
+ * - With `profile`: loads `~/.qontoctl/{profile}.yaml`
+ * - Without `profile`: tries CWD `.qontoctl.yaml`, then `~/.qontoctl.yaml`
+ */
+export declare function loadConfigFile(options?: {
+    profile?: string | undefined;
+    cwd?: string | undefined;
+    home?: string | undefined;
+}): Promise<LoadResult>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/config/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,GAAG,EAAE,OAAO,CAAC;IACb,sEAAsE;IACtE,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,OAAO,CAAC,EAAE;IAC7C,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B,GAAG,OAAO,CAAC,UAAU,CAAC,CAqBtB"}

package/dist/config/loader.js

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { parse as parseYaml } from "yaml";
+import { CONFIG_DIR } from "../constants.js";
+const CONFIG_FILENAME = ".qontoctl.yaml";
+/**
+ * Resolves and loads the appropriate config file.
+ *
+ * - With `profile`: loads `~/.qontoctl/{profile}.yaml`
+ * - Without `profile`: tries CWD `.qontoctl.yaml`, then `~/.qontoctl.yaml`
+ */
+export async function loadConfigFile(options) {
+    const home = options?.home ?? homedir();
+    const profile = options?.profile;
+    if (profile !== undefined) {
+        const path = join(home, CONFIG_DIR, `${profile}.yaml`);
+        return loadFromPath(path);
+    }
+    const cwd = options?.cwd ?? process.cwd();
+    // Try CWD first
+    const cwdPath = join(cwd, CONFIG_FILENAME);
+    const cwdResult = await loadFromPath(cwdPath);
+    if (cwdResult.raw !== undefined) {
+        return cwdResult;
+    }
+    // Fall back to home directory
+    const homePath = join(home, CONFIG_FILENAME);
+    return loadFromPath(homePath);
+}
+async function loadFromPath(path) {
+    try {
+        const content = await readFile(path, "utf-8");
+        const raw = parseYaml(content);
+        return { raw, path };
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return { raw: undefined, path: undefined };
+        }
+        throw new Error(`Failed to read config file "${path}": ${String(error)}`);
+    }
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}
+//# sourceMappingURL=loader.js.map

package/dist/config/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,MAAM,eAAe,GAAG,gBAAgB,CAAC;AASzC;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAIpC;IACC,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,OAAO,EAAE,CAAC;IACxC,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,CAAC;IAEjC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,OAAO,OAAO,CAAC,CAAC;QACvD,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAE1C,gBAAgB;IAChB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;IAC3C,MAAM,SAAS,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,CAAC;IAC9C,IAAI,SAAS,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,8BAA8B;IAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;IAC7C,OAAO,YAAY,CAAC,QAAQ,CAAC,CAAC;AAChC,CAAC;AAED,KAAK,UAAU,YAAY,CAAC,IAAY;IACtC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC9C,MAAM,GAAG,GAAY,SAAS,CAAC,OAAO,CAAC,CAAC;QACxC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;IACvB,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAI,WAAW,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAClD,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC7C,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,MAAM,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC5E,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,CAAC;AACnD,CAAC"}

package/dist/config/resolve.d.ts

@@ -0,0 +1,19 @@
+import type { ConfigResult, ResolveOptions } from "./types.js";
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolves the full configuration by:
+ * 1. Loading the appropriate YAML config file (profile-aware)
+ * 2. Validating the schema (producing warnings for unknown keys)
+ * 3. Overlaying environment variables
+ * 4. Verifying that credentials are present
+ * 5. Resolving the API endpoint
+ *
+ * Endpoint precedence:
+ *   QONTOCTL_ENDPOINT > QONTOCTL_SANDBOX > profile endpoint > profile sandbox > default
+ *
+ * @throws {ConfigError} on validation errors or missing credentials
+ */
+export declare function resolveConfig(options?: ResolveOptions): Promise<ConfigResult>;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/config/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/config/resolve.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAM/D,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CA0CnF"}

package/dist/config/resolve.js

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { loadConfigFile } from "./loader.js";
+import { validateConfig } from "./validate.js";
+import { applyEnvOverlay } from "./env.js";
+import { API_BASE_URL, SANDBOX_BASE_URL } from "../constants.js";
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+/**
+ * Resolves the full configuration by:
+ * 1. Loading the appropriate YAML config file (profile-aware)
+ * 2. Validating the schema (producing warnings for unknown keys)
+ * 3. Overlaying environment variables
+ * 4. Verifying that credentials are present
+ * 5. Resolving the API endpoint
+ *
+ * Endpoint precedence:
+ *   QONTOCTL_ENDPOINT > QONTOCTL_SANDBOX > profile endpoint > profile sandbox > default
+ *
+ * @throws {ConfigError} on validation errors or missing credentials
+ */
+export async function resolveConfig(options) {
+    const profile = options?.profile;
+    // 1. Load config file
+    const { raw, path } = await loadConfigFile({
+        profile,
+        cwd: options?.cwd,
+        home: options?.home,
+    });
+    // 2. Validate
+    const { config: fileConfig, warnings, errors } = validateConfig(raw);
+    if (errors.length > 0) {
+        const location = path !== undefined ? ` (${path})` : "";
+        throw new ConfigError(`Invalid configuration${location}:\n  - ${errors.join("\n  - ")}`);
+    }
+    // 3. Overlay env vars
+    const config = applyEnvOverlay(fileConfig, {
+        profile,
+        env: options?.env,
+    });
+    // 4. Verify credentials are present
+    if (config.apiKey === undefined) {
+        const searchedLocations = describeSearchLocations(profile, path);
+        throw new ConfigError(`No credentials found. ${searchedLocations}`);
+    }
+    if (config.apiKey.organizationSlug === "") {
+        throw new ConfigError('Missing required field "organization-slug" in api-key credentials');
+    }
+    if (config.apiKey.secretKey === "") {
+        throw new ConfigError('Missing required field "secret-key" in api-key credentials');
+    }
+    // 5. Resolve endpoint
+    const endpoint = resolveEndpoint(config);
+    return { config, endpoint, warnings };
+}
+/**
+ * Resolves the API endpoint from config.
+ *
+ * Precedence (env overlay already applied, so env vars win over file values):
+ *   explicit endpoint > sandbox flag > default (production)
+ */
+function resolveEndpoint(config) {
+    if (config.endpoint !== undefined) {
+        return config.endpoint;
+    }
+    if (config.sandbox === true) {
+        return SANDBOX_BASE_URL;
+    }
+    return API_BASE_URL;
+}
+function describeSearchLocations(profile, loadedPath) {
+    if (profile !== undefined) {
+        return `Checked ~/.qontoctl/${profile}.yaml and QONTOCTL_${profile.toUpperCase().replaceAll("-", "_")}_* env vars.`;
+    }
+    if (loadedPath !== undefined) {
+        return `Found config at ${loadedPath} but it contains no api-key credentials. Also checked QONTOCTL_* env vars.`;
+    }
+    return "Checked .qontoctl.yaml (CWD), ~/.qontoctl.yaml (home), and QONTOCTL_* env vars.";
+}
+//# sourceMappingURL=resolve.js.map

package/dist/config/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/config/resolve.ts"],"names":[],"mappings":"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"}

package/dist/config/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * API key credentials for authenticating with the Qonto API.
+ */
+export interface ApiKeyCredentials {
+    organizationSlug: string;
+    secretKey: string;
+}
+/**
+ * Parsed configuration from a `.qontoctl.yaml` file.
+ */
+export interface QontoctlConfig {
+    apiKey?: ApiKeyCredentials;
+    endpoint?: string;
+    sandbox?: boolean;
+}
+/**
+ * Result of resolving configuration, including any warnings encountered.
+ */
+export interface ConfigResult {
+    config: QontoctlConfig;
+    /** Resolved API endpoint URL. */
+    endpoint: string;
+    warnings: string[];
+}
+/**
+ * Options for resolving configuration.
+ */
+export interface ResolveOptions {
+    /** Named profile to load from `~/.qontoctl/{profile}.yaml`. */
+    profile?: string | undefined;
+    /** Override CWD for file resolution (useful for testing). */
+    cwd?: string | undefined;
+    /** Override home directory for file resolution (useful for testing). */
+    home?: string | undefined;
+    /** Override environment variables (useful for testing). */
+    env?: Record<string, string | undefined> | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/config/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,cAAc,CAAC;IACvB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,6DAA6D;IAC7D,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;CACtD"}

package/dist/config/types.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+export {};
+//# sourceMappingURL=types.js.map

package/dist/config/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC"}

package/dist/config/validate.d.ts

@@ -0,0 +1,22 @@
+import type { QontoctlConfig } from "./types.js";
+/**
+ * Check whether a profile name is safe to use as a filename.
+ *
+ * Rejects names containing path separators (`/`, `\`) or parent-directory
+ * references (`..`) to prevent path-traversal attacks.
+ */
+export declare function isValidProfileName(name: string): boolean;
+export interface ValidationResult {
+    config: QontoctlConfig;
+    warnings: string[];
+    errors: string[];
+}
+/**
+ * Validates a parsed YAML document against the expected config schema.
+ *
+ * - Known keys with wrong types produce errors.
+ * - Unknown keys produce warnings (forward compatibility).
+ * - Returns a partially-populated config for valid fields.
+ */
+export declare function validateConfig(raw: unknown): ValidationResult;
+//# sourceMappingURL=validate.d.ts.map

package/dist/config/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/config/validate.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAKD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAsF7D"}