nsekit 0.1.1 → 0.2.0

package/README.md

@@ -6,7 +6,13 @@ Unified broker abstraction for Indian stock markets. Write your trading logic on
 npm install nsekit
 ```
 
-[GitHub](https://github.com/ilampirai/nsekit) | [docs/broker-credentials.md](docs/broker-credentials.md) | [docs/adding-a-broker.md](docs/adding-a-broker.md)
+[AI-adding-a-broker.md](docs/AI-adding-a-broker.md) | [adding-a-broker.md](docs/adding-a-broker.md) | [broker-credentials.md](docs/broker-credentials.md)
+
+| Document | Description |
+|----------|-------------|
+| [AI-adding-a-broker.md](docs/AI-adding-a-broker.md) | Self-contained prompt for any AI assistant to implement a new broker adapter end to end — from reading API docs to running tests to submitting a PR. |
+| [adding-a-broker.md](docs/adding-a-broker.md) | Step-by-step manual guide covering file structure, implementation order, common pitfalls, the 13-checkpoint integration test, and pull request checklist. |
+| [broker-credentials.md](docs/broker-credentials.md) | Per-broker credential reference — which fields are required, where to get them, auth flow details, and security notes. |
 
 ---
 
@@ -28,45 +34,102 @@ Before authenticating, review the credential fields each broker requires: [docs/
 ```typescript
 import { createBroker } from 'nsekit';
 
-// 1. Create a broker instance
+const broker = createBroker('finvasia');   // or 'zerodha', 'dhan', 'paper'
+const auth = await broker.authenticate({ userId: '...', password: '...', totpSecret: '...', apiKey: '...', vendorCode: '...' });
+const order = await broker.placeOrder({ tradingSymbol: 'RELIANCE', exchange: 'NSE', side: 'BUY', quantity: 1, type: 'LIMIT', product: 'INTRADAY', price: 2400, validity: 'DAY' });
+const cancel = await broker.cancelOrder(order.value.orderId);
+```
+
+See [docs/broker-credentials.md](docs/broker-credentials.md) for which credential fields each broker requires.
+
+---
+
+## Instrument Master
+
+Before placing orders, searching symbols, or subscribing to ticks, sync the broker's instrument master. This downloads ~180K instruments once and indexes them in memory. Every lookup after that is instant — no API calls, no delays.
+
+**It's always better to sync first, then run everything else.**
+
+```typescript
+import { createBroker, InstrumentMaster } from 'nsekit';
+
 const broker = createBroker('finvasia');
+await broker.authenticate({ /* ... */ });
 
-// 2. Authenticate
-const auth = await broker.authenticate({
-  userId: 'FA12345',
-  password: 'your_password',
-  totpSecret: 'YOUR_BASE32_SECRET',
-  apiKey: 'your_api_secret',
-  vendorCode: 'FA12345_U',
-});
-// auth.value => { accessToken: '...', userId: 'FA12345', expiresAt: 1707523199000, ... }
-
-// 3. Place an order
-const order = await broker.placeOrder({
-  tradingSymbol: 'RELIANCE-EQ',
-  exchange: 'NSE',
-  side: 'BUY',
-  quantity: 1,
-  type: 'LIMIT',
-  product: 'INTRADAY',
-  price: 2400,
-  validity: 'DAY',
+// Sync once at startup
+const imaster = new InstrumentMaster();
+await imaster.syncBroker('finvasia', broker.instruments);
+// => { instrumentCount: 184302, source: 'network' }
+
+// Now resolve, search, or trade
+const inst = imaster.resolve('NIFTY-24000-CE-27FEB26');   // exact canonical lookup
+const results = imaster.search('NIFTY', 'NFO', 'CE', 10); // fuzzy search
+```
+
+### Where instruments are stored
+
+The first sync downloads instruments from the broker and saves them to disk as JSON. On subsequent startups, `syncBroker()` loads from this cache — no network call, near-instant.
+
+```
+./InstrumentDump/                          (default location)
+  finvasia-instruments.json                (one file per broker)
+  zerodha-instruments.json
+```
+
+Custom path:
+
+```typescript
+const imaster = new InstrumentMaster({
+  instrumentFilePath: './data/instruments',
 });
-// order.value => { orderId: '26020900479551', status: 'PENDING', timestamp: 1707480649000 }
+```
 
-// 4. Get positions
-const positions = await broker.getPositions();
-// positions.value => [{ tradingSymbol: 'RELIANCE-EQ', side: 'LONG', quantity: 1, pnl: 12.50, ... }]
+To force a fresh download (skip cache):
 
-// 5. Cancel the order
-const cancel = await broker.cancelOrder(order.value.orderId);
-// cancel.value => { orderId: '26020900479551', status: 'CANCELLED' }
+```typescript
+await imaster.syncBroker('finvasia', broker.instruments, true);
+```
+
+### Multi-broker sync
+
+Syncing multiple brokers merges instruments into one index. The same instrument from different brokers (e.g. NIFTY options) becomes a single entry with both broker tokens preserved.
+
+```typescript
+await imaster.syncBroker('zerodha', zerodhaBroker.instruments);
+await imaster.syncBroker('finvasia', finvasiaBroker.instruments);
+// NIFTY-24000-CE-27FEB26 now has both zerodha and finvasia tokens
+```
+
+### Optional: Redis
+
+Pass an ioredis-compatible client to cache instruments in Redis. Useful when multiple processes (user bots, strategy bots) need instrument data without each loading 180K entries from disk.
+
+```typescript
+import Redis from 'ioredis';
+
+const imaster = new InstrumentMaster({ redis: new Redis() });
+await imaster.syncBroker('finvasia', broker.instruments);
+// All instruments now in Redis — any process with the same Redis gets O(1) lookups
 ```
 
-Switch to any other broker by changing a single line:
+### Canonical symbol format
+
+All instruments are indexed using a standardized format, regardless of which broker provided them:
+
+```
+EQ:     TATAMOTORS                      (just underlying)
+FUT:    NIFTY-FUT-27FEB26               (underlying-FUT-DDMMMYY)
+CE:     NIFTY-24000-CE-27FEB26          (underlying-strike-CE-DDMMMYY)
+PE:     NIFTY-24000-PE-27FEB26          (underlying-strike-PE-DDMMMYY)
+```
+
+Zerodha's `NIFTY26FEB24000CE` and Finvasia's `NIFTY26FEB26C24000` both resolve to `NFO:NIFTY-24000-CE-27FEB26`. You never need to think about broker-specific symbol formats.
 
 ```typescript
-const broker = createBroker('zerodha');  // or 'dhan', 'paper'
+imaster.resolve('TATAMOTORS');                    // NSE equity (NSE preferred over BSE)
+imaster.resolve('BSE:TATAMOTORS');                // explicit exchange
+imaster.resolve('NIFTY-24000-CE-27FEB26');        // NFO option
+imaster.resolve('NFO:NIFTY-FUT-27FEB26');         // with exchange prefix
 ```
 
 ---
@@ -119,13 +182,7 @@ const order = unwrap(result);
 
 ### Instrument Master
 
-The `InstrumentMaster` maintains a normalized lookup table of all tradeable instruments across brokers. Resolution follows a three-tier strategy:
-
-1. Redis hot cache (O(1) lookup for recently used instruments)
-2. In-memory index (built from broker dump files)
-3. Broker search API fallback (for brokers that support it)
-
-Each broker implements `IBrokerInstruments` with `streamDump()`, `normalize()`, `search()`, and `resolve()` methods.
+See the [Instrument Master](#instrument-master) section above for full usage. In short: each broker implements `IBrokerInstruments` with `streamDump()` and `normalize()`. The `normalize()` function sets `underlying`, `instrumentType`, `strike`, and `expiry` — `InstrumentMaster` builds canonical symbols automatically and merges entries across brokers.
 
 ### Paper Broker
 

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-export declare const VERSION = "0.1.1";
+export declare const VERSION = "0.2.0";
 export * from './types/index';
 export * from './errors/index';
 export type { IBroker } from './interfaces/broker.interface';
 export { InstrumentMaster } from './instruments/instrument-master';
+export type { InstrumentMasterOptions } from './instruments/instrument-master';
 export { WSManager } from './websocket/ws-manager';
 export { SessionManager } from './session/session-manager';
 export { ZerodhaBroker } from './brokers/zerodha/ZerodhaBroker';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,OAAO,UAAU,CAAC;AAG/B,cAAc,eAAe,CAAC;AAG9B,cAAc,gBAAgB,CAAC;AAG/B,YAAY,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAG7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAG3D,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAI1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAM7D;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAexD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,OAAO,UAAU,CAAC;AAG/B,cAAc,eAAe,CAAC;AAG9B,cAAc,gBAAgB,CAAC;AAG/B,YAAY,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAG7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,YAAY,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAG3D,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAI1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAM7D;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAexD"}

package/dist/index.js

@@ -12626,10 +12626,10 @@ var require_axios = __commonJS((exports, module) => {
     }
   }
   var CanceledError$1 = CanceledError;
-  function settle(resolve, reject, response) {
+  function settle(resolve2, reject, response) {
     const validateStatus = response.config.validateStatus;
     if (!response.status || !validateStatus || validateStatus(response.status)) {
-      resolve(response);
+      resolve2(response);
     } else {
       reject(new AxiosError$1("Request failed with status code " + response.status, [AxiosError$1.ERR_BAD_REQUEST, AxiosError$1.ERR_BAD_RESPONSE][Math.floor(response.status / 100) - 4], response.config, response.request, response));
     }
@@ -13203,7 +13203,7 @@ var require_axios = __commonJS((exports, module) => {
   }
   var isHttpAdapterSupported = typeof process !== "undefined" && utils$1.kindOf(process) === "process";
   var wrapAsync = (asyncExecutor) => {
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       let onDone;
       let isDone;
       const done = (value, isRejected) => {
@@ -13214,7 +13214,7 @@ var require_axios = __commonJS((exports, module) => {
       };
       const _resolve = (value) => {
         done(value);
-        resolve(value);
+        resolve2(value);
       };
       const _reject = (reason) => {
         done(reason, true);
@@ -13266,7 +13266,7 @@ var require_axios = __commonJS((exports, module) => {
     }
   };
   var httpAdapter = isHttpAdapterSupported && function httpAdapter(config) {
-    return wrapAsync(async function dispatchHttpRequest(resolve, reject, onDone) {
+    return wrapAsync(async function dispatchHttpRequest(resolve2, reject, onDone) {
       let { data, lookup, family, httpVersion = 1, http2Options } = config;
       const { responseType, responseEncoding } = config;
       const method = config.method.toUpperCase();
@@ -13347,7 +13347,7 @@ var require_axios = __commonJS((exports, module) => {
         }
         let convertedData;
         if (method !== "GET") {
-          return settle(resolve, reject, {
+          return settle(resolve2, reject, {
             status: 405,
             statusText: "method not allowed",
             headers: {},
@@ -13369,7 +13369,7 @@ var require_axios = __commonJS((exports, module) => {
         } else if (responseType === "stream") {
           convertedData = stream__default["default"].Readable.from(convertedData);
         }
-        return settle(resolve, reject, {
+        return settle(resolve2, reject, {
           data: convertedData,
           status: 200,
           statusText: "OK",
@@ -13556,7 +13556,7 @@ var require_axios = __commonJS((exports, module) => {
         };
         if (responseType === "stream") {
           response.data = responseStream;
-          settle(resolve, reject, response);
+          settle(resolve2, reject, response);
         } else {
           const responseBuffer = [];
           let totalResponseBytes = 0;
@@ -13595,7 +13595,7 @@ var require_axios = __commonJS((exports, module) => {
             } catch (err) {
               return reject(AxiosError$1.from(err, null, config, response.request, response));
             }
-            settle(resolve, reject, response);
+            settle(resolve2, reject, response);
           });
         }
         abortEmitter.once("abort", (err) => {
@@ -13815,7 +13815,7 @@ var require_axios = __commonJS((exports, module) => {
   };
   var isXHRAdapterSupported = typeof XMLHttpRequest !== "undefined";
   var xhrAdapter = isXHRAdapterSupported && function(config) {
-    return new Promise(function dispatchXhrRequest(resolve, reject) {
+    return new Promise(function dispatchXhrRequest(resolve2, reject) {
       const _config = resolveConfig(config);
       let requestData = _config.data;
       const requestHeaders = AxiosHeaders$1.from(_config.headers).normalize();
@@ -13847,7 +13847,7 @@ var require_axios = __commonJS((exports, module) => {
           request
         };
         settle(function _resolve(value) {
-          resolve(value);
+          resolve2(value);
           done();
         }, function _reject(err) {
           reject(err);
@@ -14198,8 +14198,8 @@ var require_axios = __commonJS((exports, module) => {
         responseType = responseType || "text";
         let responseData = await resolvers[utils$1.findKey(resolvers, responseType) || "text"](response, config);
         !isStreamResponse && unsubscribe && unsubscribe();
-        return await new Promise((resolve, reject) => {
-          settle(resolve, reject, {
+        return await new Promise((resolve2, reject) => {
+          settle(resolve2, reject, {
             data: responseData,
             headers: AxiosHeaders$1.from(response.headers),
             status: response.status,
@@ -14547,8 +14547,8 @@ var require_axios = __commonJS((exports, module) => {
         throw new TypeError("executor must be a function.");
       }
       let resolvePromise;
-      this.promise = new Promise(function promiseExecutor(resolve) {
-        resolvePromise = resolve;
+      this.promise = new Promise(function promiseExecutor(resolve2) {
+        resolvePromise = resolve2;
       });
       const token = this;
       this.promise.then((cancel) => {
@@ -14562,9 +14562,9 @@ var require_axios = __commonJS((exports, module) => {
       });
       this.promise.then = (onfulfilled) => {
         let _resolve;
-        const promise = new Promise((resolve) => {
-          token.subscribe(resolve);
-          _resolve = resolve;
+        const promise = new Promise((resolve2) => {
+          token.subscribe(resolve2);
+          _resolve = resolve2;
         }).then(onfulfilled);
         promise.cancel = function reject() {
           token.unsubscribe(_resolve);
@@ -18454,7 +18454,7 @@ var require_connect2 = __commonJS((exports) => {
       return `${this.default_login_uri}?api_key=${this.api_key}&v=3`;
     }
     generateSession(request_token, api_secret) {
-      return new Promise((resolve, reject) => {
+      return new Promise((resolve2, reject) => {
         const checksum = (0, sha256_1.default)(this.api_key + request_token + api_secret).toString();
         const p = this._post("api.token", {
           api_key: this.api_key,
@@ -18465,7 +18465,7 @@ var require_connect2 = __commonJS((exports) => {
           if (resp && resp.access_token) {
             this.setAccessToken(resp.access_token);
           }
-          return resolve(resp);
+          return resolve2(resp);
         }).catch(function(err) {
           return reject(err);
         });
@@ -18478,7 +18478,7 @@ var require_connect2 = __commonJS((exports) => {
       });
     }
     renewAccessToken(refresh_token, api_secret) {
-      return new Promise((resolve, reject) => {
+      return new Promise((resolve2, reject) => {
         const checksum = (0, sha256_1.default)(this.api_key + refresh_token + api_secret).toString();
         const p = this._post("api.token.renew", {
           api_key: this.api_key,
@@ -18489,7 +18489,7 @@ var require_connect2 = __commonJS((exports) => {
           if (resp && resp.access_token) {
             this.setAccessToken(resp.access_token);
           }
-          return resolve(resp);
+          return resolve2(resp);
         }).catch(function(err) {
           return reject(err);
         });
@@ -19297,44 +19297,63 @@ class InstrumentNotFoundError extends BrokerError {
   }
 }
 // src/instruments/instrument-master.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join, resolve } from "path";
+var DEFAULT_INSTRUMENT_PATH = "./InstrumentDump";
+
 class InstrumentMaster {
   instruments = new Map;
   tokenIndex = new Map;
   syncMeta = new Map;
   redis;
+  instrumentFilePath;
   constructor(options) {
     this.redis = options?.redis ?? null;
+    this.instrumentFilePath = resolve(options?.instrumentFilePath ?? DEFAULT_INSTRUMENT_PATH);
   }
   async syncBroker(brokerId, brokerInstruments, force = false) {
     try {
-      const existingMeta = this.syncMeta.get(brokerId);
-      if (!force && existingMeta && brokerInstruments.checkDumpChanged) {
-        const changed = await brokerInstruments.checkDumpChanged({
-          etag: existingMeta.etag,
-          lastModified: existingMeta.lastModified
-        });
-        if (!changed) {
-          return Ok(existingMeta);
+      if (!force) {
+        const diskEntries = this.loadFromDisk(brokerId);
+        if (diskEntries) {
+          this.clearBrokerEntries(brokerId);
+          for (const entry of diskEntries) {
+            this.mergeEntry(brokerId, entry);
+          }
+          const meta2 = {
+            brokerId,
+            lastSyncAt: Date.now(),
+            instrumentCount: diskEntries.length,
+            source: "disk"
+          };
+          this.syncMeta.set(brokerId, meta2);
+          if (this.redis) {
+            this.cacheInstrumentsToRedis();
+          }
+          return Ok(meta2);
         }
       }
       this.clearBrokerEntries(brokerId);
-      let count = 0;
+      const entries = [];
       if (brokerInstruments.capabilities.bulkDump && brokerInstruments.streamDump) {
         for await (const raw of brokerInstruments.streamDump()) {
           const entry = brokerInstruments.normalize(raw);
+          entries.push(entry);
           this.mergeEntry(brokerId, entry);
-          count++;
         }
       }
+      if (this.redis) {
+        this.cacheInstrumentsToRedis();
+      } else {
+        this.saveToDisk(brokerId, entries);
+      }
       const meta = {
         brokerId,
         lastSyncAt: Date.now(),
-        instrumentCount: count
+        instrumentCount: entries.length,
+        source: "network"
       };
       this.syncMeta.set(brokerId, meta);
-      if (this.redis) {
-        this.cacheInstrumentsToRedis();
-      }
       return Ok(meta);
     } catch (err) {
       return Err(err instanceof Error ? err : new Error(String(err)));
@@ -19348,9 +19367,8 @@ class InstrumentMaster {
     this.syncMeta.set(brokerId, {
       brokerId,
       lastSyncAt: Date.now(),
-      etag: existing?.etag,
-      lastModified: existing?.lastModified,
-      instrumentCount: (existing?.instrumentCount ?? 0) + entries.length
+      instrumentCount: (existing?.instrumentCount ?? 0) + entries.length,
+      source: "network"
     });
   }
   search(query, exchange, instrumentType, limit = 50) {
@@ -19396,6 +19414,35 @@ class InstrumentMaster {
       return;
     return this.instruments.get(entry.key);
   }
+  resolve(input) {
+    const { exchange, symbol } = this.parseInput(input);
+    if (exchange) {
+      const key = this.makeKey(exchange, symbol);
+      const inst = this.instruments.get(key);
+      if (inst)
+        return Ok(inst);
+      return Err(new Error(`Symbol "${symbol}" not found on ${exchange}`));
+    }
+    const matches = [];
+    for (const inst of this.instruments.values()) {
+      if (inst.tradingSymbol === symbol)
+        matches.push(inst);
+    }
+    if (matches.length === 0) {
+      return Err(new Error(`Symbol "${symbol}" not found`));
+    }
+    if (matches.length === 1) {
+      return Ok(matches[0]);
+    }
+    if (matches.length === 2) {
+      const exchanges = new Set(matches.map((m) => m.exchange));
+      if (exchanges.has("NSE") && exchanges.has("BSE")) {
+        return Ok(matches.find((m) => m.exchange === "NSE"));
+      }
+    }
+    const list = matches.slice(0, 5).map((m) => `${m.exchange}:${m.tradingSymbol}`).join(", ");
+    return Err(new Error(`Multiple matches found. Specify exchange: ${list}`));
+  }
   async getOptionChainCached(underlying, expiry) {
     const expiryDate = expiry.toISOString().slice(0, 10);
     const cacheKey = `optchain:${underlying.toUpperCase()}:${expiryDate}`;
@@ -19442,6 +19489,9 @@ class InstrumentMaster {
   get size() {
     return this.instruments.size;
   }
+  get filePath() {
+    return this.instrumentFilePath;
+  }
   getSyncMeta(brokerId) {
     return this.syncMeta.get(brokerId);
   }
@@ -19465,8 +19515,39 @@ class InstrumentMaster {
     this.tokenIndex.clear();
     this.syncMeta.clear();
   }
+  getDiskCachePath(brokerId) {
+    return join(this.instrumentFilePath, `${brokerId}-instruments.json`);
+  }
+  ensureDirectory() {
+    if (!existsSync(this.instrumentFilePath)) {
+      mkdirSync(this.instrumentFilePath, { recursive: true });
+    }
+  }
+  loadFromDisk(brokerId) {
+    const filePath = this.getDiskCachePath(brokerId);
+    try {
+      if (!existsSync(filePath))
+        return null;
+      const raw = readFileSync(filePath, "utf-8");
+      const parsed = JSON.parse(raw);
+      if (!Array.isArray(parsed))
+        return null;
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+  saveToDisk(brokerId, entries) {
+    try {
+      this.ensureDirectory();
+      const filePath = this.getDiskCachePath(brokerId);
+      const stripped = entries.map(({ raw, ...rest }) => rest);
+      writeFileSync(filePath, JSON.stringify(stripped), "utf-8");
+    } catch {}
+  }
   mergeEntry(brokerId, entry) {
-    const key = this.makeKey(entry.exchange, entry.tradingSymbol);
+    const canonical = this.buildCanonicalSymbol(entry.underlying, entry.instrumentType, entry.strike, entry.expiry);
+    const key = this.makeKey(entry.exchange, canonical);
     let instrument = this.instruments.get(key);
     if (!instrument) {
       instrument = {
@@ -19477,7 +19558,7 @@ class InstrumentMaster {
         strike: entry.strike,
         lotSize: entry.lotSize,
         tickSize: entry.tickSize,
-        tradingSymbol: entry.tradingSymbol,
+        tradingSymbol: canonical,
         brokerTokens: {}
       };
       this.instruments.set(key, instrument);
@@ -19571,6 +19652,35 @@ class InstrumentMaster {
     }
     return true;
   }
+  formatExpiry(date) {
+    const d = date instanceof Date ? date : new Date(date);
+    const dd = String(d.getDate()).padStart(2, "0");
+    const mmm = ["JAN", "FEB", "MAR", "APR", "MAY", "JUN", "JUL", "AUG", "SEP", "OCT", "NOV", "DEC"][d.getMonth()];
+    const yy = String(d.getFullYear()).slice(-2);
+    return `${dd}${mmm}${yy}`;
+  }
+  buildCanonicalSymbol(underlying, instrumentType, strike, expiry) {
+    const name = underlying.toUpperCase();
+    if (instrumentType === "EQ")
+      return name;
+    const exp = expiry ? this.formatExpiry(expiry) : "";
+    if (instrumentType === "FUT")
+      return `${name}-FUT-${exp}`;
+    const s = strike != null ? String(strike) : "0";
+    return `${name}-${s}-${instrumentType}-${exp}`;
+  }
+  parseInput(input) {
+    const upper = input.trim().toUpperCase();
+    const VALID = new Set(["NSE", "BSE", "NFO", "BFO", "MCX", "CDS"]);
+    const idx = upper.indexOf(":");
+    if (idx >= 2 && idx <= 3) {
+      const prefix = upper.slice(0, idx);
+      if (VALID.has(prefix)) {
+        return { exchange: prefix, symbol: upper.slice(idx + 1) };
+      }
+    }
+    return { symbol: upper };
+  }
   makeKey(exchange, tradingSymbol) {
     return `${exchange}:${tradingSymbol}`;
   }
@@ -23764,7 +23874,7 @@ class PaperBroker {
   }
 }
 // src/index.ts
-var VERSION = "0.1.1";
+var VERSION = "0.2.0";
 function createBroker(brokerId) {
   switch (brokerId) {
     case "zerodha":

package/dist/instruments/instrument-master.d.ts

@@ -3,13 +3,13 @@
  *
  * Maintains a Map<string, UnifiedInstrument> keyed by `{exchange}:{tradingSymbol}`.
  * Supports:
- *  - syncBroker(): stream dump from any IBrokerInstruments, normalize, merge
+ *  - syncBroker(): download + cache instruments, or load from existing cache
  *  - search(): fuzzy text search with optional exchange/type filters
  *  - getBySymbol(): exact lookup by tradingSymbol + exchange (Redis -> memory)
  *  - getByToken(): lookup by broker-specific token
  *  - getOptionChain(): filter CE/PE instruments for a given underlying + expiry
+ *  - Disk cache layer: saves normalized entries to `instrumentFilePath`
  *  - Optional Redis cache layer for distributed lookups
- *  - ETag tracking for change detection across re-syncs
  */
 import type { BrokerId, Exchange, InstrumentType } from '../types/common';
 import type { UnifiedInstrument, IBrokerInstruments, BrokerInstrumentEntry } from '../types/instruments';
@@ -23,13 +23,21 @@ export interface RedisClient {
 interface SyncMeta {
     brokerId: BrokerId;
     lastSyncAt: number;
-    etag?: string;
-    lastModified?: string;
     instrumentCount: number;
+    source: 'network' | 'disk' | 'redis';
 }
 export interface InstrumentMasterOptions {
     /** Optional Redis client (ioredis-compatible) for distributed caching. */
     redis?: RedisClient;
+    /**
+     * Path to store downloaded instrument dump files.
+     * Each broker's instruments are saved as `{brokerId}-instruments.json`.
+     *
+     * If not provided, defaults to `./InstrumentDump` relative to cwd.
+     * Make sure the path is valid and writable, or instrument dumps will
+     * be saved in the default `./InstrumentDump` folder.
+     */
+    instrumentFilePath?: string;
 }
 export declare class InstrumentMaster {
     /** Primary store: `{exchange}:{tradingSymbol}` -> UnifiedInstrument */
@@ -40,14 +48,24 @@ export declare class InstrumentMaster {
     private syncMeta;
     /** Optional Redis client for distributed cache. */
     private readonly redis;
+    /** Resolved absolute path for instrument dump files. */
+    private readonly instrumentFilePath;
     constructor(options?: InstrumentMasterOptions);
     /**
-     * Stream a broker's instrument dump, normalize each entry, and merge
-     * into the unified index. Skips re-sync if the ETag has not changed.
+     * Sync a broker's instruments into the unified index.
+     *
+     * By default, checks for existing cached data first:
+     *   - Redis available → check Redis
+     *   - No Redis → check disk (`{instrumentFilePath}/{brokerId}-instruments.json`)
+     *   - No cache → download from network via broker's streamDump()
+     *
+     * After download, saves to Redis (if available) or disk (if no Redis).
+     * Pass `force = true` to skip cache and always re-download from network.
+     * Cache refresh is the user's responsibility — call with `force = true` when needed.
      *
      * @param brokerId - Identifier for the broker being synced
      * @param brokerInstruments - The broker's IBrokerInstruments implementation
-     * @param force - Skip ETag check and force re-sync
+     * @param force - Skip cache check, force re-download from network
      */
     syncBroker(brokerId: BrokerId, brokerInstruments: IBrokerInstruments, force?: boolean): Promise<Result<SyncMeta>>;
     /**
@@ -78,25 +96,30 @@ export declare class InstrumentMaster {
      * Get an instrument by a broker-specific token.
      */
     getByToken(brokerToken: string, brokerId: BrokerId): UnifiedInstrument | undefined;
+    /**
+     * Resolve a user-friendly input to a UnifiedInstrument.
+     * Accepts formats like `"TATAMOTORS"`, `"NSE:TATAMOTORS"`, `"NIFTY-24000-CE-27FEB26"`.
+     *
+     * When no exchange is specified and the symbol exists on both NSE and BSE only,
+     * NSE is preferred. If multiple matches span other exchanges, an error is returned
+     * listing them so the caller can be explicit.
+     */
+    resolve(input: string): Result<UnifiedInstrument>;
     /**
      * Get all CE and PE instruments for a given underlying and expiry date.
      * Returns instruments sorted by strike price.
      * Results are cached in Redis (10 min TTL) when available.
-     *
-     * @param underlying - The underlying symbol (e.g. "NIFTY", "BANKNIFTY")
-     * @param expiry - The expiry date to match
      */
     getOptionChainCached(underlying: string, expiry: Date): Promise<UnifiedInstrument[]>;
     /**
      * Get all CE and PE instruments for a given underlying and expiry date.
      * Returns instruments sorted by strike price (in-memory only).
-     *
-     * @param underlying - The underlying symbol (e.g. "NIFTY", "BANKNIFTY")
-     * @param expiry - The expiry date to match
      */
     getOptionChain(underlying: string, expiry: Date): UnifiedInstrument[];
     /** Total number of instruments in the index. */
     get size(): number;
+    /** Get the resolved instrument file path. */
+    get filePath(): string;
     /** Get sync metadata for a specific broker. */
     getSyncMeta(brokerId: BrokerId): SyncMeta | undefined;
     /** Get sync metadata for all brokers. */
@@ -105,8 +128,25 @@ export declare class InstrumentMaster {
     getAll(): UnifiedInstrument[];
     /** Get all instruments for a specific exchange. */
     getByExchange(exchange: Exchange): UnifiedInstrument[];
-    /** Clear the entire index. */
+    /** Clear the entire index (memory + optionally disk/Redis). */
     clear(): void;
+    /**
+     * Get the disk cache file path for a broker.
+     */
+    private getDiskCachePath;
+    /**
+     * Ensure the instrument dump directory exists.
+     */
+    private ensureDirectory;
+    /**
+     * Load normalized instrument entries from disk cache.
+     * Returns null if file doesn't exist or is corrupt.
+     */
+    private loadFromDisk;
+    /**
+     * Save normalized instrument entries to disk.
+     */
+    private saveToDisk;
     /**
      * Merge a single BrokerInstrumentEntry into the unified index.
      * If the instrument already exists (from another broker), the broker token
@@ -122,6 +162,12 @@ export declare class InstrumentMaster {
     private scoreMatch;
     /** Check if all characters of needle appear in haystack in order. */
     private fuzzyMatch;
+    /** Format a Date as DDMMMYY (e.g. 27FEB26). */
+    private formatExpiry;
+    /** Build a canonical symbol: EQ → `TATA`, FUT → `NIFTY-FUT-27FEB26`, CE/PE → `NIFTY-24000-CE-27FEB26` */
+    private buildCanonicalSymbol;
+    /** Parse user input, splitting optional exchange prefix (e.g. `NSE:TATAMOTORS`). */
+    private parseInput;
     /** Build the canonical map key for an instrument. */
     private makeKey;
     /**

package/dist/instruments/instrument-master.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instrument-master.d.ts","sourceRoot":"","sources":["../../src/instruments/instrument-master.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"instrument-master.d.ts","sourceRoot":"","sources":["../../src/instruments/instrument-master.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nsekit",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Unified broker abstraction for Indian stock markets - CCXT-like interface for NSE/BSE brokers",
   "type": "module",
   "main": "dist/index.js",