@pungoyal/kite-cli 0.1.0

package/dist/core/errors.js

@@ -0,0 +1,152 @@
+/**
+ * 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 const ExitCode = {
+    Ok: 0,
+    /** Generic/unclassified failure. */
+    Failure: 1,
+    /** Bad CLI usage: unknown flag, missing argument, invalid value. */
+    Usage: 2,
+    /** No session, or the session expired. Run `kite login`. */
+    Auth: 3,
+    /** Kite rejected the input (InputException). */
+    Input: 4,
+    /** Order was rejected by the OMS (OrderException). */
+    Order: 5,
+    /** Insufficient funds (MarginException). */
+    Margin: 6,
+    /** Insufficient holdings to sell (HoldingException). */
+    Holding: 7,
+    /** Rate limited (HTTP 429). */
+    RateLimit: 8,
+    /** Kite or its upstream OMS is unreachable or erroring (5xx, network). */
+    Upstream: 9,
+    /** The user declined a confirmation prompt. */
+    Aborted: 10,
+    /** Confirmation required but stdin is not a TTY and --yes was not passed. */
+    ConfirmationRequired: 11,
+    /** Holdings need depository authorisation (HTTP 428). */
+    AuthorisationRequired: 12,
+    /** Trading is disabled by the local kill switch. */
+    TradingDisabled: 13,
+};
+/**
+ * Base class for every error this CLI raises deliberately. Carries an exit code
+ * and an optional remediation hint shown to the user.
+ */
+export class KiteCliError extends Error {
+    exitCode;
+    /** A short actionable next step, e.g. "Run `kite login`." */
+    hint;
+    constructor(message, exitCode = ExitCode.Failure, hint) {
+        super(message);
+        this.name = new.target.name;
+        this.exitCode = exitCode;
+        this.hint = hint;
+    }
+}
+/** An error returned by the Kite API with a structured envelope. */
+export class KiteApiError extends KiteCliError {
+    status;
+    errorType;
+    constructor(opts) {
+        super(opts.message, exitCodeForApiError(opts.status, opts.errorType), opts.hint);
+        this.status = opts.status;
+        this.errorType = opts.errorType;
+    }
+}
+/** The local session is missing or expired. */
+export class AuthRequiredError extends KiteCliError {
+    constructor(message = 'Not logged in.') {
+        super(message, ExitCode.Auth, 'Run `kite login` to start a session.');
+    }
+}
+/** Bad CLI usage — distinct from Kite rejecting valid-looking input. */
+export class UsageError extends KiteCliError {
+    constructor(message, hint) {
+        super(message, ExitCode.Usage, hint);
+    }
+}
+/** The user answered "no" at a confirmation prompt. */
+export class AbortedError extends KiteCliError {
+    constructor(message = 'Aborted.') {
+        super(message, ExitCode.Aborted);
+    }
+}
+/** Network-level failure: DNS, TCP, TLS, or timeout. */
+export class NetworkError extends KiteCliError {
+    constructor(message, hint) {
+        super(message, ExitCode.Upstream, hint);
+    }
+}
+function exitCodeForApiError(status, errorType) {
+    // Status codes that are more specific than the error_type Kite pairs them
+    // with are checked FIRST. A 428 always means "holdings need depository
+    // authorisation", but Kite sends it as a generic OrderException — matching on
+    // error_type first would collapse it to ExitCode.Order and make the
+    // documented ExitCode.AuthorisationRequired unreachable, so a script could
+    // never branch on the one condition that has a specific recovery flow.
+    if (status === 428)
+        return ExitCode.AuthorisationRequired;
+    if (status === 429)
+        return ExitCode.RateLimit;
+    switch (errorType) {
+        case 'TokenException':
+            return ExitCode.Auth;
+        case 'InputException':
+            return ExitCode.Input;
+        case 'OrderException':
+            return ExitCode.Order;
+        case 'MarginException':
+            return ExitCode.Margin;
+        case 'HoldingException':
+            return ExitCode.Holding;
+        case 'NetworkException':
+        case 'DataException':
+            return ExitCode.Upstream;
+        default:
+            break;
+    }
+    if (status === 403)
+        return ExitCode.Auth;
+    if (status >= 500)
+        return ExitCode.Upstream;
+    if (status >= 400)
+        return ExitCode.Input;
+    return ExitCode.Failure;
+}
+/**
+ * Remediation hints for the error types where the right next step is not
+ * obvious from Kite's own message.
+ */
+export function hintForApiError(status, errorType) {
+    if (errorType === 'TokenException') {
+        return 'Your session expired or was invalidated (logging into Kite web ends API sessions). Run `kite login`.';
+    }
+    // A 403 that is NOT a TokenException is a permission problem, not an expired
+    // session — most often an endpoint this app is not subscribed to (the
+    // Historical Data API, for instance, is a paid Kite add-on). Telling the user
+    // to re-login would send them round a loop that cannot fix it.
+    if (status === 403) {
+        return 'Kite denied this request. Your app may not have permission for this endpoint — historical data, for example, needs the paid Historical Data subscription. Only re-run `kite login` if your session was the problem.';
+    }
+    if (status === 428) {
+        return 'Selling these holdings needs depository authorisation. Run `kite authorise`.';
+    }
+    if (status === 429) {
+        return 'Rate limited by Kite. Quote calls are capped at 1/sec and historical at 3/sec.';
+    }
+    if (errorType === 'MarginException') {
+        return 'Check available margin with `kite funds`.';
+    }
+    if (status === 502 || status === 503 || status === 504) {
+        return "Zerodha's OMS backend is unavailable. This is usually transient; retry shortly.";
+    }
+    return undefined;
+}

package/dist/core/instruments.d.ts

@@ -0,0 +1,87 @@
+import type { KiteApi } from './api.js';
+import type { Instrument } from './schemas.js';
+/**
+ * The instrument master.
+ *
+ * Kite publishes the full instrument list as a gzipped CSV, regenerated once a
+ * day at around 08:30 IST. We cache it locally and refresh on that cadence.
+ *
+ * The critical correctness rule, quoted from Kite's docs:
+ *
+ *   "For storage, it is recommended to use a combination of exchange and
+ *    tradingsymbol as the unique key, not the numeric instrument token.
+ *    Exchanges may reuse instrument tokens for different derivative
+ *    instruments after each expiry."
+ *
+ * So the cache is keyed on `EXCHANGE:TRADINGSYMBOL` throughout. A token-keyed
+ * cache would silently resolve to the wrong contract after an expiry roll —
+ * a bug that costs money and is nearly invisible in testing.
+ *
+ * Three identifiers, three uses, easily confused:
+ *   instrument_token — the ONLY id accepted by WebSocket and historical data
+ *   tradingsymbol    — the ONLY id accepted by order placement and /quote
+ *   exchange_token   — the exchange's own id; rarely needed
+ */
+export interface InstrumentCache {
+    fetchedAt: string;
+    instruments: Instrument[];
+}
+/**
+ * Minimal RFC-4180 CSV parser.
+ *
+ * Hand-rolled rather than pulled from npm: instrument names legitimately
+ * contain commas inside quoted fields (e.g. "NIFTY 50"), so naive splitting
+ * corrupts rows — but this is ~40 lines and adding a dependency to a tool that
+ * holds trading credentials needs a better reason than that.
+ */
+export declare function parseCsv(text: string): string[][];
+export declare function parseInstrumentsCsv(csv: string): Instrument[];
+export declare class InstrumentStore {
+    private instruments;
+    private bySymbol;
+    private loaded;
+    private readonly api;
+    private readonly env;
+    constructor(api: KiteApi, env: string);
+    /** Load from cache, fetching from Kite if absent or stale. */
+    load(opts?: {
+        force?: boolean;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Load from cache only; returns false when there is no usable cache. */
+    loadCachedOnly(): Promise<boolean>;
+    private hydrate;
+    private readCache;
+    private writeCache;
+    get size(): number;
+    get all(): readonly Instrument[];
+    /** Look up by "EXCHANGE:TRADINGSYMBOL" or by exchange + symbol. */
+    lookup(exchange: string, tradingsymbol: string): Instrument | undefined;
+    lookupKey(instrumentKey: string): Instrument | undefined;
+    /**
+     * Resolve a key to an instrument token, for the WebSocket and historical
+     * endpoints (which accept nothing else).
+     */
+    requireToken(instrumentKey: string): number;
+    /**
+     * Fuzzy search over tradingsymbol and name.
+     *
+     * Ranked so that exact and prefix matches on the trading symbol come first —
+     * searching "INFY" should not bury the equity under fifty option contracts.
+     */
+    search(query: string, opts?: {
+        exchange?: string | undefined;
+        type?: string | undefined;
+        limit?: number;
+    }): Instrument[];
+}
+export interface ParsedInstrumentKey {
+    exchange: string;
+    tradingsymbol: string;
+}
+/**
+ * Parse "NSE:INFY". Defaults to NSE when no exchange is given, since that is
+ * overwhelmingly what a bare symbol means.
+ */
+export declare function parseInstrumentKey(value: string): ParsedInstrumentKey;
+export declare function formatInstrumentKey(exchange: string, tradingsymbol: string): string;

package/dist/core/instruments.js

@@ -0,0 +1,288 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { UsageError } from './errors.js';
+import { cacheDir, ensurePrivateDir, instrumentsCacheFile } from './paths.js';
+/**
+ * Minimal RFC-4180 CSV parser.
+ *
+ * Hand-rolled rather than pulled from npm: instrument names legitimately
+ * contain commas inside quoted fields (e.g. "NIFTY 50"), so naive splitting
+ * corrupts rows — but this is ~40 lines and adding a dependency to a tool that
+ * holds trading credentials needs a better reason than that.
+ */
+export function parseCsv(text) {
+    const rows = [];
+    let row = [];
+    let field = '';
+    let inQuotes = false;
+    let i = 0;
+    while (i < text.length) {
+        const char = text[i];
+        if (inQuotes) {
+            if (char === '"') {
+                if (text[i + 1] === '"') {
+                    field += '"';
+                    i += 2;
+                    continue;
+                }
+                inQuotes = false;
+                i += 1;
+                continue;
+            }
+            field += char;
+            i += 1;
+            continue;
+        }
+        if (char === '"') {
+            inQuotes = true;
+            i += 1;
+            continue;
+        }
+        if (char === ',') {
+            row.push(field);
+            field = '';
+            i += 1;
+            continue;
+        }
+        if (char === '\r') {
+            i += 1;
+            continue;
+        }
+        if (char === '\n') {
+            row.push(field);
+            rows.push(row);
+            row = [];
+            field = '';
+            i += 1;
+            continue;
+        }
+        field += char;
+        i += 1;
+    }
+    if (field !== '' || row.length > 0) {
+        row.push(field);
+        rows.push(row);
+    }
+    return rows;
+}
+export function parseInstrumentsCsv(csv) {
+    const rows = parseCsv(csv);
+    if (rows.length < 2)
+        return [];
+    const header = rows[0].map((h) => h.trim());
+    const index = (name) => header.indexOf(name);
+    const idx = {
+        instrument_token: index('instrument_token'),
+        exchange_token: index('exchange_token'),
+        tradingsymbol: index('tradingsymbol'),
+        name: index('name'),
+        last_price: index('last_price'),
+        expiry: index('expiry'),
+        strike: index('strike'),
+        tick_size: index('tick_size'),
+        lot_size: index('lot_size'),
+        instrument_type: index('instrument_type'),
+        segment: index('segment'),
+        exchange: index('exchange'),
+    };
+    const out = [];
+    for (let r = 1; r < rows.length; r += 1) {
+        const row = rows[r];
+        // Skip blank trailing lines and any truncated row.
+        if (row.length < header.length)
+            continue;
+        const token = Number(row[idx.instrument_token]);
+        const tradingsymbol = row[idx.tradingsymbol] ?? '';
+        const exchange = row[idx.exchange] ?? '';
+        if (!Number.isFinite(token) || tradingsymbol === '' || exchange === '')
+            continue;
+        out.push({
+            instrument_token: token,
+            exchange_token: numberOrUndefined(row[idx.exchange_token]),
+            tradingsymbol,
+            name: row[idx.name] || undefined,
+            // last_price in the dump is a day-old snapshot. Kept for completeness,
+            // but never surfaced as a quote.
+            last_price: numberOrUndefined(row[idx.last_price]),
+            expiry: row[idx.expiry] || undefined,
+            strike: numberOrUndefined(row[idx.strike]),
+            tick_size: numberOrUndefined(row[idx.tick_size]),
+            lot_size: numberOrUndefined(row[idx.lot_size]),
+            instrument_type: row[idx.instrument_type] || undefined,
+            segment: row[idx.segment] || undefined,
+            exchange,
+        });
+    }
+    return out;
+}
+function numberOrUndefined(value) {
+    if (value === undefined || value.trim() === '')
+        return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+}
+/** The instrument dump regenerates daily around 08:30 IST. */
+function isStale(fetchedAt, now = new Date()) {
+    const fetched = Date.parse(fetchedAt);
+    if (Number.isNaN(fetched))
+        return true;
+    const refreshHourIst = 8.5;
+    const istOffsetMs = 5.5 * 3600 * 1000;
+    const istNow = new Date(now.getTime() + istOffsetMs);
+    const istFetched = new Date(fetched + istOffsetMs);
+    // Most recent 08:30 IST boundary, as a UTC instant.
+    let boundary = Date.UTC(istNow.getUTCFullYear(), istNow.getUTCMonth(), istNow.getUTCDate(), 8, 30, 0);
+    const istHour = istNow.getUTCHours() + istNow.getUTCMinutes() / 60;
+    if (istHour < refreshHourIst) {
+        boundary -= 24 * 3600 * 1000;
+    }
+    return istFetched.getTime() < boundary;
+}
+export class InstrumentStore {
+    instruments = [];
+    bySymbol = new Map();
+    loaded = false;
+    api;
+    env;
+    constructor(api, env) {
+        this.api = api;
+        this.env = env;
+    }
+    /** Load from cache, fetching from Kite if absent or stale. */
+    async load(opts = {}) {
+        if (this.loaded && !opts.force)
+            return;
+        if (!opts.force) {
+            const cached = await this.readCache();
+            if (cached && !isStale(cached.fetchedAt)) {
+                this.hydrate(cached.instruments);
+                return;
+            }
+        }
+        const csv = await this.api.getInstrumentsCsv(undefined, opts.signal);
+        const instruments = parseInstrumentsCsv(csv);
+        this.hydrate(instruments);
+        await this.writeCache({ fetchedAt: new Date().toISOString(), instruments });
+    }
+    /** Load from cache only; returns false when there is no usable cache. */
+    async loadCachedOnly() {
+        const cached = await this.readCache();
+        if (!cached)
+            return false;
+        this.hydrate(cached.instruments);
+        return true;
+    }
+    hydrate(instruments) {
+        this.instruments = instruments;
+        this.bySymbol = new Map();
+        for (const instrument of instruments) {
+            this.bySymbol.set(key(instrument.exchange, instrument.tradingsymbol), instrument);
+        }
+        this.loaded = true;
+    }
+    async readCache() {
+        try {
+            const raw = await readFile(instrumentsCacheFile(this.env), 'utf8');
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed.instruments))
+                return null;
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    async writeCache(cache) {
+        await ensurePrivateDir(cacheDir());
+        await writeFile(instrumentsCacheFile(this.env), JSON.stringify(cache), 'utf8');
+    }
+    get size() {
+        return this.instruments.length;
+    }
+    get all() {
+        return this.instruments;
+    }
+    /** Look up by "EXCHANGE:TRADINGSYMBOL" or by exchange + symbol. */
+    lookup(exchange, tradingsymbol) {
+        return this.bySymbol.get(key(exchange, tradingsymbol));
+    }
+    lookupKey(instrumentKey) {
+        const parsed = parseInstrumentKey(instrumentKey);
+        return this.lookup(parsed.exchange, parsed.tradingsymbol);
+    }
+    /**
+     * Resolve a key to an instrument token, for the WebSocket and historical
+     * endpoints (which accept nothing else).
+     */
+    requireToken(instrumentKey) {
+        const instrument = this.lookupKey(instrumentKey);
+        if (!instrument) {
+            throw new UsageError(`Unknown instrument "${instrumentKey}".`, 'Search for it with `kite instruments search <query>`, or refresh the list with `kite instruments refresh`.');
+        }
+        return instrument.instrument_token;
+    }
+    /**
+     * Fuzzy search over tradingsymbol and name.
+     *
+     * Ranked so that exact and prefix matches on the trading symbol come first —
+     * searching "INFY" should not bury the equity under fifty option contracts.
+     */
+    search(query, opts = {}) {
+        const needle = query.trim().toUpperCase();
+        if (needle === '')
+            return [];
+        const limit = opts.limit ?? 25;
+        const scored = [];
+        for (const instrument of this.instruments) {
+            if (opts.exchange && instrument.exchange !== opts.exchange)
+                continue;
+            if (opts.type && instrument.instrument_type !== opts.type)
+                continue;
+            const symbol = instrument.tradingsymbol.toUpperCase();
+            const name = (instrument.name ?? '').toUpperCase();
+            let score = 0;
+            if (symbol === needle)
+                score = 1000;
+            else if (name === needle)
+                score = 900;
+            else if (symbol.startsWith(needle))
+                score = 800 - symbol.length;
+            else if (name.startsWith(needle))
+                score = 700 - name.length;
+            else if (symbol.includes(needle))
+                score = 500 - symbol.length;
+            else if (name.includes(needle))
+                score = 400 - name.length;
+            else
+                continue;
+            // Prefer plain equity over derivatives for an otherwise equal match.
+            if (instrument.segment === 'NSE' || instrument.segment === 'BSE')
+                score += 50;
+            scored.push({ instrument, score });
+        }
+        scored.sort((a, b) => b.score - a.score || a.instrument.tradingsymbol.localeCompare(b.instrument.tradingsymbol));
+        return scored.slice(0, limit).map((entry) => entry.instrument);
+    }
+}
+function key(exchange, tradingsymbol) {
+    return `${exchange.toUpperCase()}:${tradingsymbol.toUpperCase()}`;
+}
+/**
+ * Parse "NSE:INFY". Defaults to NSE when no exchange is given, since that is
+ * overwhelmingly what a bare symbol means.
+ */
+export function parseInstrumentKey(value) {
+    const trimmed = value.trim();
+    const colon = trimmed.indexOf(':');
+    if (colon === -1) {
+        return { exchange: 'NSE', tradingsymbol: trimmed.toUpperCase() };
+    }
+    const exchange = trimmed.slice(0, colon).toUpperCase();
+    const tradingsymbol = trimmed.slice(colon + 1).toUpperCase();
+    if (exchange === '' || tradingsymbol === '') {
+        throw new UsageError(`Malformed instrument "${value}". Expected EXCHANGE:SYMBOL, e.g. NSE:INFY.`);
+    }
+    return { exchange, tradingsymbol };
+}
+export function formatInstrumentKey(exchange, tradingsymbol) {
+    return `${exchange.toUpperCase()}:${tradingsymbol.toUpperCase()}`;
+}

package/dist/core/paths.d.ts

@@ -0,0 +1,11 @@
+export declare function configDir(): string;
+export declare function cacheDir(): string;
+export declare function configFile(): string;
+/** Non-secret session metadata (expiry, user id). The token itself is not here. */
+export declare function sessionFile(): string;
+/** Encrypted credential store, used only when the OS keyring is unavailable. */
+export declare function credentialsFile(): string;
+/** Instrument master cache, refreshed daily. */
+export declare function instrumentsCacheFile(env: string): string;
+/** Create a directory with 0700 so secrets are not world-readable. */
+export declare function ensurePrivateDir(dir: string): Promise<void>;

package/dist/core/paths.js

@@ -0,0 +1,56 @@
+import { chmod, mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * XDG-compliant paths, with the usual macOS pragmatism: we use ~/.config rather
+ * than ~/Library/Application Support, because CLI users expect their dotfiles
+ * in one place and every comparable tool (gh, aws, stripe) does the same.
+ */
+function xdg(envVar, fallback) {
+    const value = process.env[envVar];
+    if (value && value.trim() !== '')
+        return value;
+    return fallback;
+}
+export function configDir() {
+    const override = process.env['KITE_CONFIG_DIR'];
+    if (override && override.trim() !== '')
+        return override;
+    return join(xdg('XDG_CONFIG_HOME', join(homedir(), '.config')), 'kite');
+}
+export function cacheDir() {
+    const override = process.env['KITE_CACHE_DIR'];
+    if (override && override.trim() !== '')
+        return override;
+    return join(xdg('XDG_CACHE_HOME', join(homedir(), '.cache')), 'kite');
+}
+export function configFile() {
+    return join(configDir(), 'config.json');
+}
+/** Non-secret session metadata (expiry, user id). The token itself is not here. */
+export function sessionFile() {
+    return join(configDir(), 'session.json');
+}
+/** Encrypted credential store, used only when the OS keyring is unavailable. */
+export function credentialsFile() {
+    return join(configDir(), 'credentials.enc');
+}
+/** Instrument master cache, refreshed daily. */
+export function instrumentsCacheFile(env) {
+    return join(cacheDir(), `instruments.${env}.json`);
+}
+/** Create a directory with 0700 so secrets are not world-readable. */
+export async function ensurePrivateDir(dir) {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    // mkdir's mode is masked by umask, so set it explicitly. Not supported on
+    // Windows, where ACLs already restrict the user profile directory.
+    if (process.platform !== 'win32') {
+        try {
+            await chmod(dir, 0o700);
+        }
+        catch {
+            // Directory may be owned by another user in a shared setup; the write
+            // itself will fail later with a clearer error.
+        }
+    }
+}

package/dist/core/ratelimit.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Client-side rate limiting, per endpoint category.
+ *
+ * Kite's published limits (https://kite.trade/docs/connect/v3/exceptions/):
+ *
+ *   Quote            1 req/sec     <- the binding constraint in practice
+ *   Historical       3 req/sec
+ *   Order placement  10 req/sec, 400/min, 5000/day
+ *   Everything else  10 req/sec
+ *
+ * The quote limit is what bites first: a naive per-symbol loop over a watchlist
+ * is ~1000x slower than one batched /quote/ltp call, which accepts 1000
+ * instruments. Batching is handled at the client layer; this module only
+ * enforces pacing.
+ */
+export type RateCategory = 'quote' | 'historical' | 'order' | 'default';
+export declare const ORDER_LIMITS: {
+    readonly perMinute: 400;
+    readonly perDay: 5000;
+    /** Kite rejects further modifications after this many on one order. */
+    readonly modificationsPerOrder: 25;
+};
+export declare class RateLimiter {
+    private readonly buckets;
+    private readonly orderCounters;
+    private readonly now;
+    constructor(now?: () => number);
+    acquire(category: RateCategory, signal?: AbortSignal): Promise<void>;
+    /**
+     * Roll the per-minute and per-IST-day order windows forward if they have
+     * elapsed. Shared by the pre-flight cap check and the post-acquire counter so
+     * the two never disagree about which window an order falls in.
+     */
+    private rollOrderWindows;
+    /**
+     * Refuse to place another order once a documented cap is reached.
+     *
+     * These counters reset each process run, so they cannot be authoritative
+     * across invocations of a short-lived CLI — this is a backstop against a
+     * runaway loop inside ONE long-running process (`kite watch`, a scripted
+     * batch, a library embedder), not a mirror of Zerodha's server-side
+     * accounting.
+     */
+    private assertOrderCapacity;
+    /**
+     * Track the 400/min and 5000/day order caps (see {@link assertOrderCapacity},
+     * which enforces them before the order is sent).
+     */
+    private countOrder;
+    /** Orders placed by this process in the current minute / IST day. */
+    orderUsage(): {
+        minute: number;
+        day: number;
+    };
+    /** True if this process is approaching a documented order cap. */
+    nearOrderLimit(): boolean;
+}