@pungoyal/kite-cli 0.1.1 → 0.2.0

package/dist/core/profiles.js

@@ -0,0 +1,140 @@
+import { EnvironmentSchema, SANDBOX_CREDENTIALS } from './config.js';
+import { ExitCode, KiteCliError } from './errors.js';
+/**
+ * Multi-account resolution.
+ *
+ * A *profile* is a named Zerodha account. Selection is stateless per invocation
+ * — there is deliberately no sticky "active account" that persists across
+ * commands, because forgetting which account is active while placing real
+ * orders is exactly the mistake this feature must not introduce. Instead the
+ * target is resolved fresh every run, and the money-moving preview shows the
+ * verified user id (see `safety.ts`).
+ *
+ * Two profile names are reserved:
+ *   - `default`  — today's single-account setup (top-level apiKey/env in config,
+ *                  secrets stored unprefixed). Chosen so existing installs need
+ *                  no migration.
+ *   - `sandbox`  — Zerodha's public sandbox. One fixed identity, so there is no
+ *                  value in per-account sandbox profiles.
+ */
+export const DEFAULT_PROFILE = 'default';
+export const SANDBOX_PROFILE = 'sandbox';
+export const RESERVED_PROFILES = [DEFAULT_PROFILE, SANDBOX_PROFILE];
+/** Filesystem- and keyring-safe. Also keeps names out of `profile:<n>:` key collisions. */
+const PROFILE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,31}$/;
+/** Reject names that could escape a filename or collide with a reserved prefix. */
+export function assertValidProfileName(name) {
+    if (!PROFILE_NAME_RE.test(name)) {
+        throw new KiteCliError(`Invalid profile name "${name}".`, ExitCode.Usage, 'Use 1–32 characters: letters, digits, hyphen or underscore, starting alphanumeric.');
+    }
+}
+/**
+ * Keyring / encrypted-file namespace for a profile's secrets.
+ *
+ * The reserved profiles reproduce the historical env-keyed scheme byte-for-byte
+ * (`production` unprefixed, `sandbox:` otherwise), so no stored secret has to be
+ * migrated. Every other profile gets a `profile:<name>:` namespace that cannot
+ * collide with an env name.
+ */
+export function storagePrefixFor(profile) {
+    if (profile.name === DEFAULT_PROFILE || profile.name === SANDBOX_PROFILE) {
+        return profile.env === 'production' ? '' : `${profile.env}:`;
+    }
+    return `profile:${profile.name}:`;
+}
+/** Every profile the user has, reserved ones first, without duplicates. */
+export function listProfileNames(config) {
+    const names = [DEFAULT_PROFILE, SANDBOX_PROFILE];
+    for (const name of Object.keys(config.profiles)) {
+        if (!names.includes(name))
+            names.push(name);
+    }
+    return names;
+}
+export function isKnownProfile(config, name) {
+    return name === DEFAULT_PROFILE || name === SANDBOX_PROFILE || Object.hasOwn(config.profiles, name);
+}
+/**
+ * Look up a profile by name without applying command-line overrides.
+ *
+ * An unknown name yields an empty, production profile rather than throwing, so
+ * `kite --profile new login` (and `profiles add`) can create it.
+ */
+export function getProfile(config, name) {
+    if (name === SANDBOX_PROFILE) {
+        return { name, apiKey: SANDBOX_CREDENTIALS.apiKey, env: 'sandbox', trading: undefined, explicit: false };
+    }
+    if (name === DEFAULT_PROFILE) {
+        return { name, apiKey: config.apiKey ?? '', env: config.env, trading: undefined, explicit: false };
+    }
+    const p = config.profiles[name];
+    return {
+        name,
+        apiKey: p?.apiKey ?? '',
+        env: p?.env ?? 'production',
+        trading: p?.trading,
+        explicit: false,
+    };
+}
+function parseEnvFlag(value) {
+    if (value === undefined || value.trim() === '')
+        return undefined;
+    const result = EnvironmentSchema.safeParse(value);
+    if (!result.success) {
+        throw new KiteCliError(`Unknown environment "${value}". Expected "production" or "sandbox".`, ExitCode.Usage);
+    }
+    return result.data;
+}
+/**
+ * Resolve the effective profile for this invocation.
+ *
+ * Precedence: `--profile` > KITE_PROFILE > (`--env sandbox` alias) >
+ * `config.defaultProfile` > `default`. An explicit `--env`/KITE_ENV then
+ * overrides the resolved profile's environment, so `--env production` still
+ * forces production the way it always has.
+ */
+export function resolveProfile(selectors, config) {
+    const named = selectors.profileFlag?.trim() || process.env['KITE_PROFILE']?.trim() || '';
+    const explicitEnv = parseEnvFlag(selectors.envFlag ?? process.env['KITE_ENV']);
+    let name;
+    let explicit;
+    if (named) {
+        assertValidProfileName(named);
+        name = named;
+        explicit = true;
+    }
+    else if (explicitEnv === 'sandbox') {
+        // Back-compat: `--env sandbox` selects the sandbox profile. This is an alias,
+        // not an explicit account choice, so it does not arm the env-var guard.
+        name = SANDBOX_PROFILE;
+        explicit = false;
+    }
+    else {
+        name = config.defaultProfile ?? DEFAULT_PROFILE;
+        explicit = false;
+    }
+    const base = getProfile(config, name);
+    const env = explicitEnv ?? base.env;
+    // Any profile resolved into the sandbox environment uses the public demo key —
+    // in particular a `default` profile pinned to sandbox via `config.env`, which
+    // would otherwise carry the (production) config apiKey and fail to authenticate.
+    const apiKey = env === 'sandbox' ? SANDBOX_CREDENTIALS.apiKey : base.apiKey;
+    return { ...base, apiKey, env, explicit };
+}
+/**
+ * The trading config actually in force: global settings overlaid with the
+ * profile's overrides. Fail-closed by construction — a field the profile leaves
+ * unset falls back to the global value, so an omitted cap never becomes "no cap".
+ */
+export function resolveTradingConfig(config, profile) {
+    const base = config.trading;
+    const o = profile.trading;
+    if (!o)
+        return base;
+    return {
+        enabled: o.enabled ?? base.enabled,
+        confirm: o.confirm ?? base.confirm,
+        maxOrderValue: o.maxOrderValue ?? base.maxOrderValue,
+        strictConfirmAbove: o.strictConfirmAbove ?? base.strictConfirmAbove,
+    };
+}

package/dist/core/schemas.d.ts

@@ -141,11 +141,11 @@ export type Margins = z.infer<typeof MarginsSchema>;
 export type SegmentMargin = z.infer<typeof SegmentMarginSchema>;
 /** Known terminal states. Not exhaustive — see the note at the top of this file. */
 export declare const ORDER_STATUS: {
-    readonly Complete: "COMPLETE";
-    readonly Cancelled: "CANCELLED";
-    readonly Rejected: "REJECTED";
-    readonly Open: "OPEN";
-    readonly TriggerPending: "TRIGGER PENDING";
+    readonly Complete: 'COMPLETE';
+    readonly Cancelled: 'CANCELLED';
+    readonly Rejected: 'REJECTED';
+    readonly Open: 'OPEN';
+    readonly TriggerPending: 'TRIGGER PENDING';
 };
 export declare const TERMINAL_ORDER_STATUSES: Set<string>;
 export declare const OrderSchema: z.ZodObject<{
@@ -474,6 +474,79 @@ export type Gtt = z.infer<typeof GttSchema>;
 export declare const GttCreateResultSchema: z.ZodObject<{
     trigger_id: z.ZodNumber;
 }, z.core.$loose>;
+/**
+ * An ATO (Alert-Triggers-Order) alert carries a basket — a full order spec that
+ * is placed when the alert fires. Every field is optional and the object is
+ * loose: we only *read* baskets on existing alerts, and Kite's basket shape is
+ * richer than we display, so anything we don't touch must pass through
+ * untouched rather than fail parsing (invariant #5).
+ */
+export declare const AlertBasketItemSchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodString>;
+    tradingsymbol: z.ZodOptional<z.ZodString>;
+    exchange: z.ZodOptional<z.ZodString>;
+    instrument_token: z.ZodOptional<z.ZodNumber>;
+    weight: z.ZodOptional<z.ZodNumber>;
+    params: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+}, z.core.$loose>;
+export declare const AlertBasketSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    items: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        type: z.ZodOptional<z.ZodString>;
+        tradingsymbol: z.ZodOptional<z.ZodString>;
+        exchange: z.ZodOptional<z.ZodString>;
+        instrument_token: z.ZodOptional<z.ZodNumber>;
+        weight: z.ZodOptional<z.ZodNumber>;
+        params: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export declare const AlertSchema: z.ZodObject<{
+    uuid: z.ZodString;
+    user_id: z.ZodOptional<z.ZodString>;
+    type: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    status: z.ZodString;
+    disabled_reason: z.ZodOptional<z.ZodString>;
+    lhs_attribute: z.ZodOptional<z.ZodString>;
+    lhs_exchange: z.ZodOptional<z.ZodString>;
+    lhs_tradingsymbol: z.ZodOptional<z.ZodString>;
+    operator: z.ZodOptional<z.ZodString>;
+    rhs_type: z.ZodOptional<z.ZodString>;
+    rhs_attribute: z.ZodOptional<z.ZodString>;
+    rhs_exchange: z.ZodOptional<z.ZodString>;
+    rhs_tradingsymbol: z.ZodOptional<z.ZodString>;
+    rhs_constant: z.ZodOptional<z.ZodNumber>;
+    alert_count: z.ZodOptional<z.ZodNumber>;
+    basket: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        type: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        items: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            type: z.ZodOptional<z.ZodString>;
+            tradingsymbol: z.ZodOptional<z.ZodString>;
+            exchange: z.ZodOptional<z.ZodString>;
+            instrument_token: z.ZodOptional<z.ZodNumber>;
+            weight: z.ZodOptional<z.ZodNumber>;
+            params: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>;
+    created_at: z.ZodOptional<z.ZodString>;
+    updated_at: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type Alert = z.infer<typeof AlertSchema>;
+/** One entry in an alert's trigger history. `meta`/`order_meta` are large and
+ * only shown verbatim in `--json`, so they pass through unvalidated. */
+export declare const AlertHistoryEntrySchema: z.ZodObject<{
+    uuid: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodString>;
+    condition: z.ZodOptional<z.ZodString>;
+    created_at: z.ZodOptional<z.ZodString>;
+    meta: z.ZodOptional<z.ZodUnknown>;
+    order_meta: z.ZodOptional<z.ZodNullable<z.ZodUnknown>>;
+}, z.core.$loose>;
+export type AlertHistoryEntry = z.infer<typeof AlertHistoryEntrySchema>;
 export declare const OrderMarginSchema: z.ZodObject<{
     type: z.ZodOptional<z.ZodString>;
     tradingsymbol: z.ZodOptional<z.ZodString>;

package/dist/core/schemas.js

@@ -330,6 +330,61 @@ export const GttSchema = z.looseObject({
 });
 export const GttCreateResultSchema = z.looseObject({ trigger_id: z.number() });
 // ---------------------------------------------------------------------------
+// Alerts
+// ---------------------------------------------------------------------------
+/**
+ * An ATO (Alert-Triggers-Order) alert carries a basket — a full order spec that
+ * is placed when the alert fires. Every field is optional and the object is
+ * loose: we only *read* baskets on existing alerts, and Kite's basket shape is
+ * richer than we display, so anything we don't touch must pass through
+ * untouched rather than fail parsing (invariant #5).
+ */
+export const AlertBasketItemSchema = z.looseObject({
+    type: z.string().optional(),
+    tradingsymbol: z.string().optional(),
+    exchange: z.string().optional(),
+    instrument_token: z.number().optional(),
+    weight: z.number().optional(),
+    params: z.looseObject({}).optional(),
+});
+export const AlertBasketSchema = z.looseObject({
+    name: z.string().optional(),
+    type: z.string().optional(),
+    tags: z.array(z.unknown()).optional(),
+    items: z.array(AlertBasketItemSchema).default([]),
+});
+export const AlertSchema = z.looseObject({
+    uuid: z.string(),
+    user_id: z.string().optional(),
+    type: z.string(),
+    name: z.string().optional(),
+    status: z.string(),
+    disabled_reason: z.string().optional(),
+    lhs_attribute: z.string().optional(),
+    lhs_exchange: z.string().optional(),
+    lhs_tradingsymbol: z.string().optional(),
+    operator: z.string().optional(),
+    rhs_type: z.string().optional(),
+    rhs_attribute: z.string().optional(),
+    rhs_exchange: z.string().optional(),
+    rhs_tradingsymbol: z.string().optional(),
+    rhs_constant: z.number().optional(),
+    alert_count: z.number().optional(),
+    basket: AlertBasketSchema.optional(),
+    created_at: z.string().optional(),
+    updated_at: z.string().optional(),
+});
+/** One entry in an alert's trigger history. `meta`/`order_meta` are large and
+ * only shown verbatim in `--json`, so they pass through unvalidated. */
+export const AlertHistoryEntrySchema = z.looseObject({
+    uuid: z.string().optional(),
+    type: z.string().optional(),
+    condition: z.string().optional(),
+    created_at: z.string().optional(),
+    meta: z.unknown().optional(),
+    order_meta: z.unknown().nullish(),
+});
+// ---------------------------------------------------------------------------
 // Margins / charges calculator
 // ---------------------------------------------------------------------------
 export const OrderMarginSchema = z.looseObject({

package/dist/core/session.d.ts

@@ -13,15 +13,16 @@ export declare const SessionMetaSchema: z.ZodObject<{
     broker: z.ZodOptional<z.ZodString>;
     env: z.ZodString;
     apiKey: z.ZodString;
+    profile: z.ZodOptional<z.ZodString>;
     expiresAt: z.ZodString;
     loginTime: z.ZodOptional<z.ZodString>;
     exchanges: z.ZodDefault<z.ZodArray<z.ZodString>>;
     products: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type SessionMeta = z.infer<typeof SessionMetaSchema>;
-export declare function loadSessionMeta(): Promise<SessionMeta | null>;
+export declare function loadSessionMeta(profile?: string): Promise<SessionMeta | null>;
 export declare function saveSessionMeta(meta: SessionMeta): Promise<void>;
-export declare function clearSessionMeta(): Promise<void>;
+export declare function clearSessionMeta(profile?: string): Promise<void>;
 /**
  * Kite access tokens expire at 06:00 IST the following day — a regulatory
  * requirement, not a configurable session length.

package/dist/core/session.js

@@ -15,16 +15,18 @@ export const SessionMetaSchema = z.object({
     broker: z.string().optional(),
     env: z.string(),
     apiKey: z.string(),
+    /** The profile this session belongs to. Optional so pre-profile files parse. */
+    profile: z.string().optional(),
     /** ISO 8601. Kite invalidates all tokens at 06:00 IST daily. */
     expiresAt: z.string(),
     loginTime: z.string().optional(),
     exchanges: z.array(z.string()).default([]),
     products: z.array(z.string()).default([]),
 });
-export async function loadSessionMeta() {
+export async function loadSessionMeta(profile = 'default') {
     let raw;
     try {
-        raw = await readFile(sessionFile(), 'utf8');
+        raw = await readFile(sessionFile(profile), 'utf8');
     }
     catch (err) {
         if (err.code === 'ENOENT')
@@ -41,7 +43,7 @@ export async function loadSessionMeta() {
 }
 export async function saveSessionMeta(meta) {
     await ensurePrivateDir(configDir());
-    const path = sessionFile();
+    const path = sessionFile(meta.profile ?? 'default');
     await writeFile(path, `${JSON.stringify(meta, null, 2)}\n`, {
         mode: 0o600,
         encoding: 'utf8',
@@ -50,9 +52,9 @@ export async function saveSessionMeta(meta) {
         await chmod(path, 0o600);
     }
 }
-export async function clearSessionMeta() {
+export async function clearSessionMeta(profile = 'default') {
     try {
-        await unlink(sessionFile());
+        await unlink(sessionFile(profile));
     }
     catch (err) {
         if (err.code !== 'ENOENT')

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export { type ClientOptions, KiteClient, setDispatcher, } from './core/client.js
 export { type Endpoints, type Environment, endpointsFor, SANDBOX_CREDENTIALS, } from './core/config.js';
 export { AuthRequiredError, ExitCode, KiteApiError, KiteCliError, type KiteErrorType, NetworkError, UsageError, } from './core/errors.js';
 export { InstrumentStore, parseInstrumentKey, parseInstrumentsCsv, } from './core/instruments.js';
+export { DEFAULT_PROFILE, getProfile, listProfileNames, type ResolvedProfile, resolveProfile, resolveTradingConfig, SANDBOX_PROFILE, storagePrefixFor, } from './core/profiles.js';
 export { ORDER_LIMITS, type RateCategory, RateLimiter, } from './core/ratelimit.js';
 export { maskSecret, redact, redactString, redactUrl, registerSecret, } from './core/redact.js';
 export * from './core/schemas.js';

package/dist/index.js

@@ -11,6 +11,7 @@ export { KiteClient, setDispatcher, } from './core/client.js';
 export { endpointsFor, SANDBOX_CREDENTIALS, } from './core/config.js';
 export { AuthRequiredError, ExitCode, KiteApiError, KiteCliError, NetworkError, UsageError, } from './core/errors.js';
 export { InstrumentStore, parseInstrumentKey, parseInstrumentsCsv, } from './core/instruments.js';
+export { DEFAULT_PROFILE, getProfile, listProfileNames, resolveProfile, resolveTradingConfig, SANDBOX_PROFILE, storagePrefixFor, } from './core/profiles.js';
 export { ORDER_LIMITS, RateLimiter, } from './core/ratelimit.js';
 export { maskSecret, redact, redactString, redactUrl, registerSecret, } from './core/redact.js';
 export * from './core/schemas.js';

package/dist/run.js

@@ -43,6 +43,7 @@ export async function run(opts = {}) {
         .option('--quiet', 'Suppress informational messages')
         .option('--debug', 'Print redacted request diagnostics to stderr')
         .option('--env <env>', 'Environment: production or sandbox')
+        .option('--profile <name>', 'Account profile to use (see `kite profiles`)')
         .option('-y, --yes', 'Skip confirmation prompts (use with care)')
         .option('--dry-run', 'Show what would happen without sending anything to Kite')
         .showHelpAfterError('(run `kite --help` for usage)')
@@ -70,10 +71,12 @@ export async function run(opts = {}) {
     // Registered lazily so a bare `kite quote` never pays to import the
     // dashboard renderer, the ticker, or the prompt library.
     const { authCommands } = await import('./commands/auth.js');
+    const { profileCommands } = await import('./commands/profiles.js');
     const { portfolioCommands } = await import('./commands/portfolio.js');
     const { marketCommands } = await import('./commands/market.js');
     const { orderCommands } = await import('./commands/orders.js');
     const { gttCommands } = await import('./commands/gtt.js');
+    const { alertCommands } = await import('./commands/alerts.js');
     const { watchCommands } = await import('./commands/watch.js');
     const { configCommands } = await import('./commands/config.js');
     // commandsGroup applies to every command registered after it, so the group
@@ -81,6 +84,7 @@ export async function run(opts = {}) {
     // difference between a readable --help and a wall of text.
     program.commandsGroup('Account:');
     authCommands(program, withContext);
+    profileCommands(program, withContext);
     program.commandsGroup('Portfolio:');
     portfolioCommands(program, withContext);
     program.commandsGroup('Market data:');
@@ -88,6 +92,7 @@ export async function run(opts = {}) {
     program.commandsGroup('Trading:');
     orderCommands(program, withContext);
     gttCommands(program, withContext);
+    alertCommands(program, withContext);
     program.commandsGroup('Streaming:');
     watchCommands(program, withContext);
     program.commandsGroup('Settings:');
@@ -102,6 +107,7 @@ Examples:
   $ kite orders place NSE:INFY -s BUY -q 1 --dry-run
                                                 Preview an order without sending it
   $ kite positions --json | jq '.net[].pnl'     Machine-readable output
+  $ kite --profile huf holdings                 Run against another account (kite profiles)
 
 Safety:
   Order commands preview the resolved order and ask for confirmation.

package/dist/safety.js

@@ -106,10 +106,14 @@ function renderPreview(ctx, opts, force = false) {
     const { io } = ctx;
     if ((io.json || io.quiet) && !force)
         return;
-    const width = Math.max(...opts.details.map((d) => d.label.length));
+    const width = Math.max('Account'.length, ...opts.details.map((d) => d.label.length));
     const emit = force ? (text) => io.forceNote(text) : (text) => io.note(text);
     emit('');
     emit(io.bold(opts.action));
+    // Which account this will hit, first and by verified identity — not just the
+    // profile label a user chose, which can point at the wrong app. This is the
+    // primary guard against placing an order on the wrong account.
+    emit(`  ${io.dim('Account'.padEnd(width))}  ${accountLine(ctx)}`);
     for (const detail of opts.details) {
         emit(`  ${io.dim(detail.label.padEnd(width))}  ${detail.value}`);
     }
@@ -117,6 +121,13 @@ function renderPreview(ctx, opts, force = false) {
         emit(`  ${io.cyan('sandbox — no real money involved')}`);
     }
 }
+/** The verified identity behind this invocation, with the profile for context. */
+function accountLine(ctx) {
+    const { io, session, profile } = ctx;
+    const who = session ? `${session.userName ?? session.userId} (${session.userId})` : io.dim('token from environment');
+    const suffix = profile.name === 'default' ? '' : ` · profile ${io.bold(profile.name)}`;
+    return `${who}${suffix}`;
+}
 /**
  * Generate a unique order tag.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pungoyal/kite-cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Unofficial command-line interface for the Zerodha Kite Connect API — not affiliated with or endorsed by Zerodha",
   "keywords": [
     "zerodha",
@@ -44,7 +44,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "dev": "node --experimental-strip-types src/cli.ts",
+    "dev": "tsx src/cli.ts",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
@@ -79,7 +79,8 @@
     "msw": "^2.15.0",
     "publint": "^0.3.0",
     "strip-ansi": "^7.1.0",
-    "typescript": "^5.8.0",
+    "tsx": "^4.23.1",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.10"
   }
 }