@pungoyal/kite-cli 0.1.0

package/dist/core/api.js

@@ -0,0 +1,472 @@
+import { z } from 'zod';
+import { UsageError } from './errors.js';
+import { AuctionSchema, BasketMarginSchema, CandlesSchema, GttCreateResultSchema, GttSchema, HoldingSchema, LtpMapSchema, MarginsSchema, MfHoldingSchema, MfOrderSchema, MfSipSchema, OhlcMapSchema, OrderMarginSchema, OrderSchema, PlaceOrderResultSchema, PositionsSchema, ProfileSchema, QuoteMapSchema, SessionSchema, TradeSchema, } from './schemas.js';
+export const VARIETIES = ['regular', 'amo', 'co', 'iceberg', 'auction'];
+export const ORDER_TYPES = ['MARKET', 'LIMIT', 'SL', 'SL-M'];
+export const PRODUCTS = ['CNC', 'NRML', 'MIS', 'MTF'];
+export const VALIDITIES = ['DAY', 'IOC', 'TTL'];
+export const EXCHANGES = ['NSE', 'BSE', 'NFO', 'CDS', 'BCD', 'MCX', 'BFO'];
+export class KiteApi {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    // -------------------------------------------------------------------------
+    // Session
+    // -------------------------------------------------------------------------
+    /** Exchange a request_token for an access_token. */
+    async createSession(params) {
+        return this.client.request({
+            method: 'POST',
+            path: '/session/token',
+            schema: SessionSchema,
+            form: {
+                api_key: this.client.apiKey,
+                request_token: params.requestToken,
+                checksum: params.checksum,
+            },
+        });
+    }
+    async invalidateSession(accessToken) {
+        return this.client.request({
+            method: 'DELETE',
+            path: '/session/token',
+            schema: z.unknown(),
+            query: { api_key: this.client.apiKey, access_token: accessToken },
+        });
+    }
+    async getProfile(signal) {
+        return this.client.request({
+            method: 'GET',
+            path: '/user/profile',
+            schema: ProfileSchema,
+            signal,
+        });
+    }
+    async getMargins(signal) {
+        return this.client.request({
+            method: 'GET',
+            path: '/user/margins',
+            schema: MarginsSchema,
+            signal,
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Orders
+    // -------------------------------------------------------------------------
+    async getOrders(signal) {
+        return this.client.request({
+            method: 'GET',
+            path: '/orders',
+            schema: z.array(OrderSchema),
+            signal,
+        });
+    }
+    /** Returns the full state history of one order, oldest first. */
+    async getOrderHistory(orderId, signal) {
+        return this.client.request({
+            method: 'GET',
+            path: `/orders/${encodeURIComponent(orderId)}`,
+            schema: z.array(OrderSchema),
+            signal,
+        });
+    }
+    async getTrades(signal) {
+        return this.client.request({
+            method: 'GET',
+            path: '/trades',
+            schema: z.array(TradeSchema),
+            signal,
+        });
+    }
+    async getOrderTrades(orderId, signal) {
+        return this.client.request({
+            method: 'GET',
+            path: `/orders/${encodeURIComponent(orderId)}/trades`,
+            schema: z.array(TradeSchema),
+            signal,
+        });
+    }
+    /**
+     * Place an order.
+     *
+     * This is never retried automatically anywhere in the stack. If it fails at
+     * the network level the caller must reconcile via `findOrderByTag`, because
+     * a timed-out request may still have been executed.
+     */
+    async placeOrder(params, signal) {
+        const { variety, ...rest } = params;
+        return this.client.request({
+            method: 'POST',
+            path: `/orders/${variety}`,
+            category: 'order',
+            schema: PlaceOrderResultSchema,
+            form: rest,
+            signal,
+        });
+    }
+    async modifyOrder(params, signal) {
+        const { variety, order_id, ...rest } = params;
+        return this.client.request({
+            method: 'PUT',
+            path: `/orders/${variety}/${encodeURIComponent(order_id)}`,
+            category: 'order',
+            schema: z.looseObject({ order_id: z.string() }),
+            form: rest,
+            signal,
+        });
+    }
+    async cancelOrder(params, signal) {
+        return this.client.request({
+            method: 'DELETE',
+            path: `/orders/${params.variety}/${encodeURIComponent(params.order_id)}`,
+            category: 'order',
+            schema: z.looseObject({ order_id: z.string() }),
+            query: params.parent_order_id ? { parent_order_id: params.parent_order_id } : undefined,
+            signal,
+        });
+    }
+    /**
+     * Reconciliation helper for the no-idempotency problem.
+     *
+     * Kite has no client-suppliable idempotency key (the `guid` field in the
+     * response is server-assigned, despite its confusing description). Zerodha's
+     * own guidance for a failed/timed-out placement is: do NOT retry — fetch the
+     * orderbook and look for your tag. Only place again if it is absent.
+     */
+    async findOrderByTag(tag, signal) {
+        const orders = await this.getOrders(signal);
+        return orders.filter((order) => order.tag === tag || order.tags?.includes(tag));
+    }
+    // -------------------------------------------------------------------------
+    // GTT
+    // -------------------------------------------------------------------------
+    async getGtts(signal) {
+        return this.client.request({
+            method: 'GET',
+            path: '/gtt/triggers',
+            schema: z.array(GttSchema),
+            signal,
+        });
+    }
+    async getGtt(id, signal) {
+        return this.client.request({
+            method: 'GET',
+            path: `/gtt/triggers/${id}`,
+            schema: GttSchema,
+            signal,
+        });
+    }
+    async placeGtt(params, signal) {
+        return this.client.request({
+            method: 'POST',
+            path: '/gtt/triggers',
+            schema: GttCreateResultSchema,
+            form: serialiseGtt(params),
+            signal,
+        });
+    }
+    async modifyGtt(id, params, signal) {
+        return this.client.request({
+            method: 'PUT',
+            path: `/gtt/triggers/${id}`,
+            schema: GttCreateResultSchema,
+            form: serialiseGtt(params),
+            signal,
+        });
+    }
+    async deleteGtt(id, signal) {
+        return this.client.request({
+            method: 'DELETE',
+            path: `/gtt/triggers/${id}`,
+            schema: GttCreateResultSchema,
+            signal,
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Portfolio
+    // -------------------------------------------------------------------------
+    async getHoldings(signal) {
+        return this.client.request({
+            method: 'GET',
+            path: '/portfolio/holdings',
+            schema: z.array(HoldingSchema),
+            signal,
+        });
+    }
+    async getPositions(signal) {
+        return this.client.request({
+            method: 'GET',
+            path: '/portfolio/positions',
+            schema: PositionsSchema,
+            signal,
+        });
+    }
+    async getAuctions(signal) {
+        return this.client.request({
+            method: 'GET',
+            path: '/portfolio/holdings/auctions',
+            schema: z.array(AuctionSchema),
+            signal,
+        });
+    }
+    /** Convert a position between products. Note this is PUT, not POST. */
+    async convertPosition(params, signal) {
+        return this.client.request({
+            method: 'PUT',
+            path: '/portfolio/positions',
+            schema: z.boolean().or(z.unknown()),
+            form: params,
+            signal,
+        });
+    }
+    /**
+     * Initiate CDSL authorisation for selling holdings — the HTTP 428 recovery
+     * path.
+     *
+     * With no ISINs this authorises the whole demat account; with ISINs it
+     * authorises only those instruments. The client encodes an array as repeated
+     * `isin` form fields, which is the shape Kite expects.
+     */
+    async authoriseHoldings(isins, signal) {
+        return this.client.request({
+            method: 'POST',
+            path: '/portfolio/holdings/authorise',
+            schema: z.looseObject({ request_id: z.string() }),
+            form: isins?.length ? { isin: isins } : {},
+            signal,
+        });
+    }
+    /** Browser URL the user must visit to complete a holdings authorisation. */
+    authorisationUrl(requestId) {
+        return `https://kite.zerodha.com/connect/portfolio/authorise/holdings/${encodeURIComponent(this.client.apiKey)}/${encodeURIComponent(requestId)}`;
+    }
+    // -------------------------------------------------------------------------
+    // Market data
+    // -------------------------------------------------------------------------
+    /**
+     * Full quotes. Kite caps this at 500 instruments per call and 1 request per
+     * second, so large lists are chunked and paced by the limiter.
+     */
+    async getQuote(instruments, signal) {
+        return this.batchedQuote(instruments, 500, '/quote', QuoteMapSchema, signal);
+    }
+    /** OHLC + last price. Caps at 1000 instruments per call. */
+    async getOhlc(instruments, signal) {
+        return this.batchedQuote(instruments, 1000, '/quote/ohlc', OhlcMapSchema, signal);
+    }
+    /** Last traded price only. Caps at 1000 instruments per call. */
+    async getLtp(instruments, signal) {
+        return this.batchedQuote(instruments, 1000, '/quote/ltp', LtpMapSchema, signal);
+    }
+    async batchedQuote(instruments, chunkSize, path, schema, signal) {
+        if (instruments.length === 0)
+            return {};
+        const merged = {};
+        for (const chunk of chunks(instruments, chunkSize)) {
+            const result = await this.client.request({
+                method: 'GET',
+                path,
+                category: 'quote',
+                schema,
+                query: { i: chunk },
+                signal,
+            });
+            Object.assign(merged, result);
+        }
+        return merged;
+    }
+    /**
+     * Historical candles, transparently chunked to respect per-interval range
+     * limits, then merged and de-duplicated.
+     */
+    async getHistorical(params, signal) {
+        const maxDays = MAX_DAYS_PER_REQUEST[params.interval];
+        const ranges = splitDateRange(params.from, params.to, maxDays);
+        const all = [];
+        for (const range of ranges) {
+            const result = await this.client.request({
+                method: 'GET',
+                path: `/instruments/historical/${params.instrument_token}/${params.interval}`,
+                category: 'historical',
+                schema: CandlesSchema,
+                query: {
+                    from: formatIstDateTime(range.from),
+                    to: formatIstDateTime(range.to),
+                    continuous: params.continuous ? 1 : undefined,
+                    oi: params.oi ? 1 : undefined,
+                },
+                signal,
+            });
+            all.push(...result.candles);
+        }
+        // Chunk boundaries are inclusive on both ends, so adjacent ranges can
+        // repeat a candle. De-duplicate on timestamp, preserving order.
+        const seen = new Set();
+        return all.filter((candle) => {
+            const key = candle[0];
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        });
+    }
+    /** The daily instrument dump as raw CSV. Not an API envelope. */
+    async getInstrumentsCsv(exchange, signal) {
+        return this.client.requestText({
+            path: exchange ? `/instruments/${exchange}` : '/instruments',
+            // /instruments is the one route the sandbox does NOT serve under /oms.
+            noPrefix: true,
+            signal,
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Margins & charges (JSON bodies, unlike the rest of the API)
+    // -------------------------------------------------------------------------
+    async orderMargins(orders, signal) {
+        return this.client.request({
+            method: 'POST',
+            path: '/margins/orders',
+            schema: z.array(OrderMarginSchema),
+            json: orders,
+            signal,
+        });
+    }
+    async basketMargins(orders, considerPositions = true, signal) {
+        return this.client.request({
+            method: 'POST',
+            path: '/margins/basket',
+            schema: BasketMarginSchema,
+            query: { consider_positions: considerPositions },
+            json: orders,
+            signal,
+        });
+    }
+    async orderCharges(orders, signal) {
+        return this.client.request({
+            method: 'POST',
+            path: '/charges/orders',
+            schema: z.array(OrderMarginSchema),
+            json: orders,
+            signal,
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Mutual funds (read-only — the current docs state that placing MF orders is
+    // not available over the API because it requires a bank debit)
+    // -------------------------------------------------------------------------
+    async getMfHoldings(signal) {
+        return this.client.request({
+            method: 'GET',
+            path: '/mf/holdings',
+            schema: z.array(MfHoldingSchema),
+            signal,
+        });
+    }
+    /** Note: only returns the last 7 days of orders. */
+    async getMfOrders(signal) {
+        return this.client.request({
+            method: 'GET',
+            path: '/mf/orders',
+            schema: z.array(MfOrderSchema),
+            signal,
+        });
+    }
+    async getMfSips(signal) {
+        return this.client.request({
+            method: 'GET',
+            path: '/mf/sips',
+            schema: z.array(MfSipSchema),
+            signal,
+        });
+    }
+}
+/**
+ * GTT takes JSON-encoded strings inside form fields — not a JSON body, and not
+ * plain form fields. An easy thing to get wrong.
+ */
+function serialiseGtt(params) {
+    return {
+        type: params.type,
+        condition: JSON.stringify(params.condition),
+        orders: JSON.stringify(params.orders),
+    };
+}
+// ---------------------------------------------------------------------------
+// Historical helpers
+// ---------------------------------------------------------------------------
+export const HISTORICAL_INTERVALS = [
+    'minute',
+    '3minute',
+    '5minute',
+    '10minute',
+    '15minute',
+    '30minute',
+    '60minute',
+    'day',
+];
+/**
+ * Maximum date range per request, by interval.
+ *
+ * These limits are NOT in the official docs — they come from Zerodha staff on
+ * the developer forum. The `day` value is 1900 rather than the 2000 quoted
+ * there, because Zerodha's own sandbox chunking helper uses 1900 and the docs
+ * note that larger `day` ranges error out.
+ */
+export const MAX_DAYS_PER_REQUEST = {
+    minute: 60,
+    '3minute': 100,
+    '5minute': 100,
+    '10minute': 100,
+    '15minute': 200,
+    '30minute': 200,
+    '60minute': 400,
+    day: 1900,
+};
+export function parseInterval(value) {
+    if (HISTORICAL_INTERVALS.includes(value)) {
+        return value;
+    }
+    throw new UsageError(`Unknown interval "${value}".`, `Supported intervals: ${HISTORICAL_INTERVALS.join(', ')}.`);
+}
+const DAY_MS = 86_400_000;
+export function splitDateRange(from, to, maxDays) {
+    if (from.getTime() > to.getTime()) {
+        throw new UsageError('`--from` must be earlier than `--to`.');
+    }
+    const ranges = [];
+    let cursor = from.getTime();
+    const end = to.getTime();
+    const span = maxDays * DAY_MS;
+    while (cursor <= end) {
+        const chunkEnd = Math.min(cursor + span, end);
+        ranges.push({ from: new Date(cursor), to: new Date(chunkEnd) });
+        if (chunkEnd >= end)
+            break;
+        // Step one second past the chunk end so ranges do not overlap by a full day.
+        cursor = chunkEnd + 1000;
+    }
+    return ranges;
+}
+/** Kite expects "yyyy-mm-dd hh:mm:ss" in IST. */
+export function formatIstDateTime(date) {
+    const parts = new Intl.DateTimeFormat('en-CA', {
+        timeZone: 'Asia/Kolkata',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hour12: false,
+    }).formatToParts(date);
+    const get = (type) => parts.find((p) => p.type === type)?.value ?? '00';
+    // Intl can render midnight as hour "24" in some locales/engines.
+    const hour = get('hour') === '24' ? '00' : get('hour');
+    return `${get('year')}-${get('month')}-${get('day')} ${hour}:${get('minute')}:${get('second')}`;
+}
+export function* chunks(items, size) {
+    for (let i = 0; i < items.length; i += size) {
+        yield items.slice(i, i + size);
+    }
+}

package/dist/core/auth.d.ts

@@ -0,0 +1,68 @@
+import type { Endpoints } from './config.js';
+/**
+ * The Kite Connect login handshake.
+ *
+ *   1. Open https://kite.zerodha.com/connect/login?v=3&api_key=...
+ *   2. User authenticates in their browser (including mandatory TOTP 2FA).
+ *   3. Kite redirects to the registered URL with ?request_token=...
+ *   4. POST /session/token with checksum = SHA256(api_key + request_token + api_secret)
+ *
+ * The CLI never sees the user's password or TOTP. We deliberately do not offer
+ * to store a TOTP seed: holding the 2FA secret alongside the API secret would
+ * collapse both factors into one, which is precisely what the SEBI 2FA mandate
+ * exists to prevent.
+ */
+/** checksum = SHA256(api_key + request_token + api_secret), hex. */
+export declare function computeChecksum(apiKey: string, requestToken: string, apiSecret: string): string;
+/**
+ * Postback checksum — note this is a DIFFERENT concatenation from the login
+ * checksum: SHA256(order_id + order_timestamp + api_secret).
+ */
+export declare function computePostbackChecksum(orderId: string, orderTimestamp: string, apiSecret: string): string;
+export declare function verifyPostbackChecksum(received: string, orderId: string, orderTimestamp: string, apiSecret: string): boolean;
+/**
+ * Constant-time string comparison that cannot throw.
+ *
+ * `timingSafeEqual` requires equal BYTE lengths and throws RangeError
+ * otherwise, so the length guard must be on the encoded buffers — not on
+ * `String.length`, which counts UTF-16 code units and can match while the byte
+ * lengths differ. Both call sites compare attacker-influenced input.
+ */
+export declare function safeCompare(a: string, b: string): boolean;
+export interface LoginUrlOptions {
+    apiKey: string;
+    endpoints: Endpoints;
+    /** Opaque CSRF value echoed back by Kite via redirect_params. */
+    state: string;
+}
+export declare function buildLoginUrl(opts: LoginUrlOptions): string;
+export declare function generateState(): string;
+export interface CallbackResult {
+    requestToken: string;
+}
+export interface CallbackServerOptions {
+    port: number;
+    path: string;
+    state: string;
+    timeoutMs?: number;
+}
+/**
+ * Run a one-shot loopback HTTP server to capture the request_token.
+ *
+ * Kite's developer console requires HTTPS for redirect URLs but explicitly
+ * permits plain http:// for localhost and 127.0.0.1, which is the standard
+ * pattern for native apps. We bind to 127.0.0.1 specifically (never 0.0.0.0),
+ * so the callback is not reachable from the network.
+ */
+export declare function waitForCallback(opts: CallbackServerOptions): {
+    promise: Promise<CallbackResult>;
+    close: () => void;
+};
+export declare function redirectUrlFor(port: number, path: string): string;
+/**
+ * Open a URL in the user's default browser.
+ *
+ * The URL is passed as an argv element to a fixed binary, never through a
+ * shell, so a crafted URL cannot become command injection.
+ */
+export declare function openBrowser(url: string): Promise<boolean>;