@pungoyal/kite-cli 0.1.0

package/dist/core/config.d.ts

@@ -0,0 +1,114 @@
+import { z } from 'zod';
+/**
+ * User configuration, persisted at ~/.config/kite/config.json.
+ *
+ * Note what is deliberately absent: there is no `yes` / `assumeYes` setting.
+ * Bypassing a confirmation prompt must be explicit at the call site every time,
+ * so `--yes` is a flag only. A config file that silently disables confirmations
+ * is exactly how an accidental order gets placed.
+ */
+export declare const EnvironmentSchema: z.ZodEnum<{
+    production: "production";
+    sandbox: "sandbox";
+}>;
+export type Environment = z.infer<typeof EnvironmentSchema>;
+export declare const ConfigSchema: z.ZodObject<{
+    apiKey: z.ZodOptional<z.ZodString>;
+    env: z.ZodDefault<z.ZodEnum<{
+        production: "production";
+        sandbox: "sandbox";
+    }>>;
+    trading: z.ZodPrefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        confirm: z.ZodDefault<z.ZodBoolean>;
+        maxOrderValue: z.ZodOptional<z.ZodNumber>;
+        strictConfirmAbove: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    output: z.ZodPrefault<z.ZodObject<{
+        color: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            always: "always";
+            never: "never";
+        }>>;
+        compact: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    redirectPort: z.ZodDefault<z.ZodNumber>;
+    redirectPath: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export type Config = z.infer<typeof ConfigSchema>;
+export declare function defaultConfig(): Config;
+export declare function loadConfig(): Promise<Config>;
+export declare function saveConfig(config: Config): Promise<void>;
+/**
+ * The settings `kite config set` accepts.
+ *
+ * Declared explicitly rather than inferred from the schema, because optional
+ * settings with no default (maxOrderValue) are indistinguishable from unknown
+ * keys otherwise. This also drives value coercion and `--help` text.
+ *
+ * Note what is absent: there is no key for skipping confirmations. `--yes`
+ * must be passed at the call site every time.
+ */
+export declare const SETTABLE_KEYS: {
+    readonly apiKey: {
+        readonly type: "string";
+        readonly description: "Kite Connect API key";
+    };
+    readonly env: {
+        readonly type: "string";
+        readonly description: "production or sandbox";
+    };
+    readonly 'trading.enabled': {
+        readonly type: "boolean";
+        readonly description: "Master kill switch for all order commands";
+    };
+    readonly 'trading.confirm': {
+        readonly type: "boolean";
+        readonly description: "Require confirmation before money-moving actions";
+    };
+    readonly 'trading.maxOrderValue': {
+        readonly type: "number";
+        readonly description: "Refuse any single order above this rupee value";
+    };
+    readonly 'trading.strictConfirmAbove': {
+        readonly type: "number";
+        readonly description: "Above this rupee value, require typing the symbol to confirm";
+    };
+    readonly 'output.color': {
+        readonly type: "string";
+        readonly description: "auto, always, or never";
+    };
+    readonly 'output.compact': {
+        readonly type: "boolean";
+        readonly description: "Render tables without borders";
+    };
+    readonly redirectPort: {
+        readonly type: "number";
+        readonly description: "Loopback port for the login callback";
+    };
+    readonly redirectPath: {
+        readonly type: "string";
+        readonly description: "Path component of the login callback URL";
+    };
+};
+export type SettableKey = keyof typeof SETTABLE_KEYS;
+export declare function isSettableKey(key: string): key is SettableKey;
+/** Environment-specific API endpoints. */
+export interface Endpoints {
+    api: string;
+    ws: string;
+    login: string;
+    /**
+     * Sandbox serves every route under an /oms prefix — except /instruments.
+     * Production has no prefix.
+     */
+    routePrefix: string;
+}
+export declare function endpointsFor(env: Environment): Endpoints;
+/** Public sandbox credentials, documented at https://kite.trade/docs/connect/v3/sandbox/ */
+export declare const SANDBOX_CREDENTIALS: {
+    readonly apiKey: "sandboxdemo";
+    readonly apiSecret: "sandboxdemo-secret";
+};
+/** Resolve the effective environment: --env flag > KITE_ENV > config > production. */
+export declare function resolveEnv(flag: string | undefined, config: Config): Environment;

package/dist/core/config.js

@@ -0,0 +1,163 @@
+import { chmod, readFile, writeFile } from 'node:fs/promises';
+import { z } from 'zod';
+import { ExitCode, KiteCliError } from './errors.js';
+import { configDir, configFile, ensurePrivateDir } from './paths.js';
+/**
+ * User configuration, persisted at ~/.config/kite/config.json.
+ *
+ * Note what is deliberately absent: there is no `yes` / `assumeYes` setting.
+ * Bypassing a confirmation prompt must be explicit at the call site every time,
+ * so `--yes` is a flag only. A config file that silently disables confirmations
+ * is exactly how an accidental order gets placed.
+ */
+export const EnvironmentSchema = z.enum(['production', 'sandbox']);
+export const ConfigSchema = z.object({
+    /** Kite Connect API key. Semi-public (it appears in login URLs), so not a keyring secret. */
+    apiKey: z.string().min(1).optional(),
+    env: EnvironmentSchema.default('production'),
+    trading: z
+        .object({
+        /**
+         * Local kill switch. When false, every order-placing, order-modifying and
+         * GTT-mutating command refuses before touching the network.
+         */
+        enabled: z.boolean().default(true),
+        /** Require an interactive confirmation before any money-moving action. */
+        confirm: z.boolean().default(true),
+        /**
+         * Refuse any single order whose notional value exceeds this (rupees).
+         * Undefined means no cap.
+         */
+        maxOrderValue: z.number().positive().optional(),
+        /**
+         * Above this notional value, require typing a literal token to confirm
+         * rather than a single keystroke.
+         */
+        strictConfirmAbove: z.number().positive().default(100_000),
+    })
+        .prefault({}),
+    output: z
+        .object({
+        color: z.enum(['auto', 'always', 'never']).default('auto'),
+        /** Default table style. */
+        compact: z.boolean().default(false),
+    })
+        .prefault({}),
+    /** Fixed loopback port for the OAuth redirect. Must match the developer console. */
+    redirectPort: z.number().int().min(1).max(65535).default(51101),
+    /** Path component of the redirect URL, e.g. "/callback". */
+    redirectPath: z.string().startsWith('/').default('/callback'),
+});
+export function defaultConfig() {
+    return ConfigSchema.parse({});
+}
+export async function loadConfig() {
+    let raw;
+    try {
+        raw = await readFile(configFile(), 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return defaultConfig();
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new KiteCliError(`Config file at ${configFile()} is not valid JSON.`, ExitCode.Failure, 'Fix it by hand, or delete it to start from defaults.');
+    }
+    const result = ConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new KiteCliError(`Config file at ${configFile()} is invalid:\n${z.prettifyError(result.error)}`, ExitCode.Failure);
+    }
+    return result.data;
+}
+export async function saveConfig(config) {
+    await ensurePrivateDir(configDir());
+    const path = configFile();
+    await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, {
+        mode: 0o600,
+        encoding: 'utf8',
+    });
+    if (process.platform !== 'win32') {
+        await chmod(path, 0o600);
+    }
+}
+/**
+ * The settings `kite config set` accepts.
+ *
+ * Declared explicitly rather than inferred from the schema, because optional
+ * settings with no default (maxOrderValue) are indistinguishable from unknown
+ * keys otherwise. This also drives value coercion and `--help` text.
+ *
+ * Note what is absent: there is no key for skipping confirmations. `--yes`
+ * must be passed at the call site every time.
+ */
+export const SETTABLE_KEYS = {
+    apiKey: { type: 'string', description: 'Kite Connect API key' },
+    env: { type: 'string', description: 'production or sandbox' },
+    'trading.enabled': {
+        type: 'boolean',
+        description: 'Master kill switch for all order commands',
+    },
+    'trading.confirm': {
+        type: 'boolean',
+        description: 'Require confirmation before money-moving actions',
+    },
+    'trading.maxOrderValue': {
+        type: 'number',
+        description: 'Refuse any single order above this rupee value',
+    },
+    'trading.strictConfirmAbove': {
+        type: 'number',
+        description: 'Above this rupee value, require typing the symbol to confirm',
+    },
+    'output.color': { type: 'string', description: 'auto, always, or never' },
+    'output.compact': {
+        type: 'boolean',
+        description: 'Render tables without borders',
+    },
+    redirectPort: {
+        type: 'number',
+        description: 'Loopback port for the login callback',
+    },
+    redirectPath: {
+        type: 'string',
+        description: 'Path component of the login callback URL',
+    },
+};
+export function isSettableKey(key) {
+    return Object.hasOwn(SETTABLE_KEYS, key);
+}
+export function endpointsFor(env) {
+    if (env === 'sandbox') {
+        return {
+            api: 'https://sandbox.kite.trade',
+            ws: 'wss://ws-sandbox.kite.trade',
+            login: 'https://sandbox.kite.trade/connect/login',
+            routePrefix: '/oms',
+        };
+    }
+    return {
+        api: 'https://api.kite.trade',
+        ws: 'wss://ws.kite.trade',
+        login: 'https://kite.zerodha.com/connect/login',
+        routePrefix: '',
+    };
+}
+/** Public sandbox credentials, documented at https://kite.trade/docs/connect/v3/sandbox/ */
+export const SANDBOX_CREDENTIALS = {
+    apiKey: 'sandboxdemo',
+    apiSecret: 'sandboxdemo-secret',
+};
+/** Resolve the effective environment: --env flag > KITE_ENV > config > production. */
+export function resolveEnv(flag, config) {
+    const candidate = flag ?? process.env['KITE_ENV'] ?? config.env;
+    const result = EnvironmentSchema.safeParse(candidate);
+    if (!result.success) {
+        throw new KiteCliError(`Unknown environment "${candidate}". Expected "production" or "sandbox".`, ExitCode.Usage);
+    }
+    return result.data;
+}

package/dist/core/credentials.d.ts

@@ -0,0 +1,27 @@
+export type SecretName = 'api_secret' | 'access_token';
+export type Backend = 'env' | 'keyring' | 'file';
+export interface CredentialLookup {
+    value: string;
+    backend: Backend;
+}
+/** True when an OS keyring is present and usable on this machine. */
+export declare function keyringAvailable(): Promise<boolean>;
+export interface CredentialStoreOptions {
+    env: string;
+    /** Passphrase for the file backend when the keyring is unavailable. */
+    passphrase?: string | undefined;
+}
+/**
+ * Read a secret, trying each backend in priority order.
+ *
+ * Every value returned is registered with the redactor, so it is scrubbed from
+ * any subsequent log, error, or stack trace even if it reaches an unexpected
+ * code path.
+ */
+export declare function getSecret(name: SecretName, opts: CredentialStoreOptions): Promise<CredentialLookup | null>;
+export declare function setSecret(name: SecretName, value: string, opts: CredentialStoreOptions): Promise<Backend>;
+export declare function deleteSecret(name: SecretName, opts: CredentialStoreOptions): Promise<void>;
+/** Remove every stored secret for an environment. Used by `kite logout --all`. */
+export declare function deleteAllSecrets(opts: CredentialStoreOptions): Promise<void>;
+/** True when secrets are being supplied entirely by the environment. */
+export declare function usingEnvCredentials(): boolean;

package/dist/core/credentials.js

@@ -0,0 +1,182 @@
+import { ExitCode, KiteCliError } from './errors.js';
+import { registerSecret } from './redact.js';
+import { decryptFromFile, deleteCredentialFile, encryptToFile } from './secretstore.js';
+/**
+ * Layered credential storage.
+ *
+ *   1. Environment variables  — always win, never persisted. This is what makes
+ *      CI, Docker, and headless servers work (cf. gh's GH_TOKEN escape hatch).
+ *   2. OS keyring             — macOS Keychain / Windows Credential Manager /
+ *                               Linux Secret Service, via @napi-rs/keyring.
+ *   3. Encrypted file         — scrypt + AES-256-GCM at ~/.config/kite, 0600.
+ *
+ * keytar is deliberately not used: the repository was archived in 2022 and it
+ * depends on prebuild-install, an install-time network fetch that npm v12 now
+ * blocks by default.
+ */
+const SERVICE = 'kite-cli';
+/** Env var that supplies each secret, bypassing all persistent storage. */
+const ENV_VAR = {
+    api_secret: 'KITE_API_SECRET',
+    access_token: 'KITE_ACCESS_TOKEN',
+};
+/**
+ * `@napi-rs/keyring` is loaded lazily and defensively. On a headless Linux box
+ * with no D-Bus the *module* imports fine but every operation throws, so we
+ * probe on use rather than on import.
+ */
+let keyringModule;
+async function loadKeyring() {
+    if (keyringModule !== undefined)
+        return keyringModule;
+    if (process.env['KITE_DISABLE_KEYRING'] === '1') {
+        keyringModule = null;
+        return null;
+    }
+    try {
+        keyringModule = await import('@napi-rs/keyring');
+    }
+    catch {
+        // No prebuilt binary for this platform, or the native module failed to
+        // load. Fall through to the encrypted file.
+        keyringModule = null;
+    }
+    return keyringModule;
+}
+async function keyringGet(account) {
+    const mod = await loadKeyring();
+    if (!mod)
+        return null;
+    try {
+        const entry = new mod.Entry(SERVICE, account);
+        // Note: @napi-rs/keyring returns null for a missing entry rather than
+        // throwing (unlike keytar). A bare try/catch would treat "absent" as
+        // success, so the null check is load-bearing.
+        return entry.getPassword() ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+async function keyringSet(account, value) {
+    const mod = await loadKeyring();
+    if (!mod)
+        return false;
+    try {
+        new mod.Entry(SERVICE, account).setPassword(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function keyringDelete(account) {
+    const mod = await loadKeyring();
+    if (!mod)
+        return;
+    try {
+        new mod.Entry(SERVICE, account).deletePassword();
+    }
+    catch {
+        // Nothing stored, or the keyring is locked. Either way there is nothing
+        // actionable for the caller.
+    }
+}
+/** True when an OS keyring is present and usable on this machine. */
+export async function keyringAvailable() {
+    const mod = await loadKeyring();
+    if (!mod)
+        return false;
+    try {
+        // A read against a name we never write. Succeeding (with null) proves the
+        // backend is reachable; throwing proves it is not.
+        new mod.Entry(SERVICE, '__probe__').getPassword();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Passphrase for the encrypted-file backend. Supplied via env, or prompted for
+ * interactively by the caller (which passes it in here).
+ */
+function filePassphrase() {
+    const value = process.env['KITE_CREDENTIALS_PASSPHRASE'];
+    return value && value !== '' ? value : null;
+}
+/** Namespaced account key, so sandbox and production sessions coexist. */
+function accountKey(name, env) {
+    return env === 'production' ? name : `${env}:${name}`;
+}
+/**
+ * Read a secret, trying each backend in priority order.
+ *
+ * Every value returned is registered with the redactor, so it is scrubbed from
+ * any subsequent log, error, or stack trace even if it reaches an unexpected
+ * code path.
+ */
+export async function getSecret(name, opts) {
+    const fromEnv = process.env[ENV_VAR[name]];
+    if (fromEnv && fromEnv.trim() !== '') {
+        registerSecret(fromEnv);
+        return { value: fromEnv, backend: 'env' };
+    }
+    const account = accountKey(name, opts.env);
+    const fromKeyring = await keyringGet(account);
+    if (fromKeyring) {
+        registerSecret(fromKeyring);
+        return { value: fromKeyring, backend: 'keyring' };
+    }
+    const passphrase = opts.passphrase ?? filePassphrase();
+    if (passphrase) {
+        const bag = await decryptFromFile(passphrase);
+        const value = bag?.[account];
+        if (value) {
+            registerSecret(value);
+            return { value, backend: 'file' };
+        }
+    }
+    return null;
+}
+export async function setSecret(name, value, opts) {
+    registerSecret(value);
+    const account = accountKey(name, opts.env);
+    if (await keyringSet(account, value)) {
+        return 'keyring';
+    }
+    const passphrase = opts.passphrase ?? filePassphrase();
+    if (!passphrase) {
+        throw new KiteCliError('No OS keyring is available on this machine and no passphrase was supplied.', ExitCode.Failure, 'Set KITE_CREDENTIALS_PASSPHRASE to enable the encrypted file store, or supply credentials via KITE_API_SECRET / KITE_ACCESS_TOKEN.');
+    }
+    const existing = (await decryptFromFile(passphrase)) ?? {};
+    existing[account] = value;
+    await encryptToFile(existing, passphrase);
+    return 'file';
+}
+export async function deleteSecret(name, opts) {
+    const account = accountKey(name, opts.env);
+    await keyringDelete(account);
+    const passphrase = opts.passphrase ?? filePassphrase();
+    if (passphrase) {
+        const existing = await decryptFromFile(passphrase);
+        if (existing && account in existing) {
+            delete existing[account];
+            if (Object.keys(existing).length === 0) {
+                await deleteCredentialFile();
+            }
+            else {
+                await encryptToFile(existing, passphrase);
+            }
+        }
+    }
+}
+/** Remove every stored secret for an environment. Used by `kite logout --all`. */
+export async function deleteAllSecrets(opts) {
+    await deleteSecret('access_token', opts);
+    await deleteSecret('api_secret', opts);
+}
+/** True when secrets are being supplied entirely by the environment. */
+export function usingEnvCredentials() {
+    return Boolean(process.env[ENV_VAR.access_token] || process.env[ENV_VAR.api_secret]);
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Error taxonomy for the Kite Connect API and this CLI.
+ *
+ * Kite returns errors as:
+ *   { "status": "error", "message": "...", "error_type": "GeneralException" }
+ *
+ * See https://kite.trade/docs/connect/v3/exceptions/
+ */
+/** Process exit codes. Distinct per failure mode so scripts can branch on them. */
+export declare const ExitCode: {
+    readonly Ok: 0;
+    /** Generic/unclassified failure. */
+    readonly Failure: 1;
+    /** Bad CLI usage: unknown flag, missing argument, invalid value. */
+    readonly Usage: 2;
+    /** No session, or the session expired. Run `kite login`. */
+    readonly Auth: 3;
+    /** Kite rejected the input (InputException). */
+    readonly Input: 4;
+    /** Order was rejected by the OMS (OrderException). */
+    readonly Order: 5;
+    /** Insufficient funds (MarginException). */
+    readonly Margin: 6;
+    /** Insufficient holdings to sell (HoldingException). */
+    readonly Holding: 7;
+    /** Rate limited (HTTP 429). */
+    readonly RateLimit: 8;
+    /** Kite or its upstream OMS is unreachable or erroring (5xx, network). */
+    readonly Upstream: 9;
+    /** The user declined a confirmation prompt. */
+    readonly Aborted: 10;
+    /** Confirmation required but stdin is not a TTY and --yes was not passed. */
+    readonly ConfirmationRequired: 11;
+    /** Holdings need depository authorisation (HTTP 428). */
+    readonly AuthorisationRequired: 12;
+    /** Trading is disabled by the local kill switch. */
+    readonly TradingDisabled: 13;
+};
+export type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];
+/** Kite's documented `error_type` values. */
+export type KiteErrorType = 'TokenException' | 'UserException' | 'OrderException' | 'InputException' | 'MarginException' | 'HoldingException' | 'NetworkException' | 'DataException' | 'GeneralException';
+/**
+ * Base class for every error this CLI raises deliberately. Carries an exit code
+ * and an optional remediation hint shown to the user.
+ */
+export declare class KiteCliError extends Error {
+    readonly exitCode: ExitCodeValue;
+    /** A short actionable next step, e.g. "Run `kite login`." */
+    readonly hint: string | undefined;
+    constructor(message: string, exitCode?: ExitCodeValue, hint?: string);
+}
+/** An error returned by the Kite API with a structured envelope. */
+export declare class KiteApiError extends KiteCliError {
+    readonly status: number;
+    readonly errorType: KiteErrorType | string;
+    constructor(opts: {
+        message: string;
+        status: number;
+        errorType: KiteErrorType | string;
+        hint?: string;
+    });
+}
+/** The local session is missing or expired. */
+export declare class AuthRequiredError extends KiteCliError {
+    constructor(message?: string);
+}
+/** Bad CLI usage — distinct from Kite rejecting valid-looking input. */
+export declare class UsageError extends KiteCliError {
+    constructor(message: string, hint?: string);
+}
+/** The user answered "no" at a confirmation prompt. */
+export declare class AbortedError extends KiteCliError {
+    constructor(message?: string);
+}
+/** Network-level failure: DNS, TCP, TLS, or timeout. */
+export declare class NetworkError extends KiteCliError {
+    constructor(message: string, hint?: string);
+}
+/**
+ * Remediation hints for the error types where the right next step is not
+ * obvious from Kite's own message.
+ */
+export declare function hintForApiError(status: number, errorType: string): string | undefined;