@ganaka/sdk 1.5.0 → 1.7.0

package/README.md

@@ -16,172 +16,218 @@ pnpm add @ganaka/sdk
 
 ## Quick Start
 
+### Using GanakaClient for Standalone API Calls
+
+The `GanakaClient` allows you to fetch data without setting up a full ganaka run:
+
 ```typescript
 import { GanakaClient } from "@ganaka/sdk";
+import dotenv from "dotenv";
+
+dotenv.config();
 
-// Initialize the client
+// Initialize the client (reads DEVELOPER_KEY from environment)
+const client = new GanakaClient();
+
+// Or with explicit configuration
 const client = new GanakaClient({
-  apiKey: "your-api-key",
-  baseUrl: "https://api.ganaka.com",
-  debug: true,
+  developerToken: "your-developer-token",
+  apiDomain: "https://api.ganaka.live", // optional, defaults to this
+});
+
+// Fetch historical candles
+const candles = await client.fetchCandles({
+  symbol: "RELIANCE",
+  interval: "1minute",
+  start_datetime: "2026-01-20T09:15:00",
+  end_datetime: "2026-01-20T15:30:00",
 });
 
-// Check API health
-const health = await client.health();
-console.log(health);
+// Fetch quote for a symbol
+const quote = await client.fetchQuote({
+  symbol: "RELIANCE",
+  datetime: "2026-01-20T10:30:00",
+});
 
-// Get shortlists
-const shortlists = await client.getShortlists();
-if (shortlists.success) {
-  console.log("Shortlists:", shortlists.data);
-}
+// Fetch shortlist
+const shortlist = await client.fetchShortlist({
+  type: "top-gainers",
+  datetime: "2026-01-20T10:30:00",
+});
 ```
 
-## Configuration
+### Using ganaka() for Iterative Strategies
+
+The `ganaka()` function is used for running iterative strategies with time loops:
 
 ```typescript
-const client = new GanakaClient({
-  apiKey: "your-api-key", // API key for authentication
-  baseUrl: "http://localhost:3000", // API base URL
-  wsUrl: "ws://localhost:3000", // WebSocket URL for real-time data
-  timeout: 30000, // Request timeout in milliseconds
-  debug: false, // Enable debug logging
+import { ganaka } from "@ganaka/sdk";
+import dotenv from "dotenv";
+
+dotenv.config();
+
+await ganaka({
+  fn: async ({ fetchCandles, fetchQuote, placeOrder, currentTimestamp }) => {
+    // Your strategy logic here
+    const candles = await fetchCandles({
+      symbol: "RELIANCE",
+      interval: "1minute",
+      start_datetime: "2026-01-20T09:15:00",
+      end_datetime: currentTimestamp,
+    });
+
+    const quote = await fetchQuote({
+      symbol: "RELIANCE",
+      datetime: currentTimestamp,
+    });
+
+    // Place order if conditions are met
+    if (quote && quote.price > 100) {
+      await placeOrder({
+        nseSymbol: "RELIANCE",
+        entryPrice: quote.price,
+        stopLossPrice: quote.price * 0.95,
+        takeProfitPrice: quote.price * 1.05,
+        datetime: currentTimestamp,
+      });
+    }
+  },
+  startTime: "2026-01-20T09:15:00",
+  endTime: "2026-01-20T15:30:00",
+  intervalMinutes: 1,
+  name: "My Strategy",
+  tags: ["momentum", "scalping"],
 });
 ```
 
-## API Methods
+## Configuration
 
-### Shortlists
+### Environment Variables
 
-```typescript
-// Get all shortlists
-const shortlists = await client.getShortlists();
+The SDK reads configuration from environment variables:
 
-// Get a specific shortlist
-const shortlist = await client.getShortlist("shortlist-id");
+- `DEVELOPER_KEY` - Your developer token (required)
+- `API_DOMAIN` - API base URL (optional, defaults to `https://api.ganaka.live`)
 
-// Create a new shortlist
-const newShortlist = await client.createShortlist({
-  name: "My Watchlist",
-  symbols: ["AAPL", "GOOGL", "MSFT"],
-});
+### GanakaClient Configuration
 
-// Update a shortlist
-const updated = await client.updateShortlist("shortlist-id", {
-  name: "Updated Watchlist",
-});
+```typescript
+import { GanakaClient } from "@ganaka/sdk";
 
-// Delete a shortlist
-await client.deleteShortlist("shortlist-id");
+const client = new GanakaClient({
+  developerToken: "your-developer-token", // optional if DEVELOPER_KEY env var is set
+  apiDomain: "https://api.ganaka.live", // optional, defaults to this
+});
 ```
 
-### Instruments
+## API Methods
 
-```typescript
-// Search instruments
-const results = await client.searchInstruments("apple");
+### GanakaClient Methods
 
-// Get instrument details
-const instrument = await client.getInstrument("AAPL");
+All methods return promises that resolve to the API response data.
 
-// Get multiple instruments
-const instruments = await client.getInstruments(["AAPL", "GOOGL"]);
-```
+#### `fetchCandles(params)`
 
-### Strategies
+Fetch historical candles for a symbol.
 
 ```typescript
-// Get all strategies
-const strategies = await client.getStrategies();
-
-// Create a strategy
-const strategy = await client.createStrategy({
-  name: "My Strategy",
-  type: "momentum",
-  parameters: {
-    period: 20,
-    threshold: 0.02,
-  },
-  status: "inactive",
+const candles = await client.fetchCandles({
+  symbol: "RELIANCE",
+  interval: "1minute", // or "5minute", "1day", etc.
+  start_datetime: "2026-01-20T09:15:00", // IST format (YYYY-MM-DDTHH:mm:ss)
+  end_datetime: "2026-01-20T15:30:00",
 });
-
-// Start/stop a strategy
-await client.startStrategy("strategy-id");
-await client.stopStrategy("strategy-id");
 ```
 
-### Orders
+#### `fetchQuote(params)`
+
+Fetch quote for a symbol at a specific datetime.
 
 ```typescript
-// Place an order
-const order = await client.placeOrder({
-  symbol: "AAPL",
-  quantity: 100,
-  orderType: "market",
-  side: "buy",
+const quote = await client.fetchQuote({
+  symbol: "RELIANCE",
+  datetime: "2026-01-20T10:30:00", // IST format
 });
-
-// Get orders
-const orders = await client.getOrders();
-
-// Cancel an order
-await client.cancelOrder("order-id");
 ```
 
-## WebSocket - Real-time Data
+#### `fetchQuoteTimeline(symbol, end_datetime)`
 
-```typescript
-// Get WebSocket client
-const ws = client.getWebSocket();
+Fetch quote timeline for a symbol.
 
-// Connect to WebSocket
-await client.connectWebSocket();
+```typescript
+const timeline = await client.fetchQuoteTimeline(
+  "RELIANCE",
+  "2026-01-20T15:30:00" // IST format
+);
+```
 
-// Subscribe to events
-ws.on("connected", () => {
-  console.log("Connected to real-time data");
-});
+#### `fetchNiftyQuote(params)`
 
-ws.on("tick", (data) => {
-  console.log("Tick data:", data);
-});
+Fetch NIFTY quote at a specific datetime.
 
-ws.on("error", (error) => {
-  console.error("WebSocket error:", error);
+```typescript
+const niftyQuote = await client.fetchNiftyQuote({
+  datetime: "2026-01-20T10:30:00", // IST format
 });
+```
 
-// Subscribe to tick data for symbols
-ws.subscribeTicks(["AAPL", "GOOGL"]);
+#### `fetchNiftyQuoteTimeline(end_datetime)`
 
-// Unsubscribe
-ws.unsubscribeTicks(["AAPL"]);
+Fetch NIFTY quote timeline.
 
-// Disconnect
-client.disconnectWebSocket();
+```typescript
+const niftyTimeline = await client.fetchNiftyQuoteTimeline(
+  "2026-01-20T15:30:00" // IST format
+);
 ```
 
-## Error Handling
+#### `fetchShortlist(queryParams)`
 
-All API methods return an `ApiResponse` object with the following structure:
+Fetch shortlist for a specific type and datetime.
 
 ```typescript
-interface ApiResponse<T> {
-  success: boolean;
-  data?: T;
-  error?: string;
-  message?: string;
-}
+const shortlist = await client.fetchShortlist({
+  type: "top-gainers", // or "top-losers", etc.
+  datetime: "2026-01-20T10:30:00", // IST format
+});
 ```
 
-Example error handling:
+#### `fetchShortlistPersistence(queryParams)`
+
+Fetch shortlist persistence - stocks that consistently appeared in a shortlist over a time range.
 
 ```typescript
-const response = await client.getShortlists();
+const persistence = await client.fetchShortlistPersistence({
+  type: "top-gainers",
+  start_datetime: "2026-01-20T09:15:00", // IST format
+  end_datetime: "2026-01-20T15:30:00", // IST format
+});
+```
 
-if (response.success) {
-  console.log("Data:", response.data);
-} else {
-  console.error("Error:", response.error);
+### ganaka() Function
+
+The `ganaka()` function provides a `RunContext` with all the above methods plus:
+
+- `placeOrder(data)` - Place an order (only available within a run context)
+- `currentTimestamp` - Current timestamp in IST format for the current loop iteration
+
+## Error Handling
+
+All methods throw errors if the API request fails. Handle them with try-catch:
+
+```typescript
+try {
+  const candles = await client.fetchCandles({
+    symbol: "RELIANCE",
+    interval: "1minute",
+    start_datetime: "2026-01-20T09:15:00",
+    end_datetime: "2026-01-20T15:30:00",
+  });
+  console.log("Candles:", candles);
+} catch (error) {
+  if (error instanceof Error) {
+    console.error("Failed to fetch candles:", error.message);
+  }
 }
 ```
 
@@ -190,7 +236,14 @@ if (response.success) {
 This SDK is written in TypeScript and provides full type definitions:
 
 ```typescript
-import type { Shortlist, Instrument, Order, Strategy, User } from "@ganaka/sdk";
+import type {
+  GanakaClient,
+  GanakaClientConfig,
+  FetchCandlesResponse,
+  FetchQuoteResponse,
+  FetchShortlistResponse,
+  RunContext,
+} from "@ganaka/sdk";
 ```
 
 ## Development
@@ -238,23 +291,3 @@ MIT
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

package/dist/index.d.ts

@@ -178,6 +178,113 @@ export declare function ganaka<T>({ fn, startTime, endTime, intervalMinutes, del
     tags?: string[];
 }): Promise<void>;
 
+/**
+ * GanakaClient provides standalone access to Ganaka API methods without requiring a run context.
+ * This allows you to fetch data (candles, quotes, shortlists, etc.) without setting up a full ganaka run.
+ *
+ * @example
+ * ```typescript
+ * import { GanakaClient } from "@ganaka/sdk";
+ *
+ * const client = new GanakaClient();
+ * const candles = await client.fetchCandles({
+ *   symbol: "RELIANCE",
+ *   interval: "1minute",
+ *   start_datetime: "2026-01-20T09:15:00",
+ *   end_datetime: "2026-01-20T15:30:00",
+ * });
+ * ```
+ */
+export declare class GanakaClient {
+    private developerToken;
+    private apiDomain;
+    constructor(config?: GanakaClientConfig);
+    /**
+     * Fetch historical candles for a symbol.
+     *
+     * @param params - Query parameters for fetching candles
+     * @param params.symbol - The symbol to fetch candles for
+     * @param params.interval - The interval for candles (e.g., "1minute", "5minute", "1day")
+     * @param params.start_datetime - Start datetime in IST string format (YYYY-MM-DDTHH:mm:ss)
+     * @param params.end_datetime - End datetime in IST string format (YYYY-MM-DDTHH:mm:ss)
+     * @returns Promise resolving to candle data
+     */
+    fetchCandles(params: z.infer<typeof v1_developer_groww_schemas.getGrowwHistoricalCandles.query>): Promise<z.infer<typeof v1_developer_groww_schemas.getGrowwHistoricalCandles.response>["data"]>;
+    /**
+     * Fetch quote for a symbol at a specific datetime.
+     *
+     * @param params - Query parameters for fetching quote
+     * @param params.symbol - The symbol to fetch quote for
+     * @param params.datetime - Datetime in IST string format (YYYY-MM-DDTHH:mm:ss)
+     * @returns Promise resolving to quote data or null
+     */
+    fetchQuote(params: z.infer<typeof v1_developer_groww_schemas.getGrowwQuote.query>): Promise<z.infer<typeof v1_developer_groww_schemas.getGrowwQuote.response>["data"] | null>;
+    /**
+     * Fetch quote timeline for a symbol.
+     * Given a symbol and an end_datetime, returns the quote timeline for the given date.
+     *
+     * @param symbol - The symbol to fetch quote timeline for
+     * @param end_datetime - End datetime in IST string format (YYYY-MM-DDTHH:mm:ss)
+     * @returns Promise resolving to quote timeline data
+     */
+    fetchQuoteTimeline(symbol: string, end_datetime: string): Promise<z.infer<typeof v1_developer_groww_schemas.getGrowwQuoteTimeline.response>["data"]["quoteTimeline"]>;
+    /**
+     * Fetch NIFTY quote at a specific datetime.
+     *
+     * @param params - Query parameters for fetching NIFTY quote
+     * @param params.datetime - Datetime in IST string format (YYYY-MM-DDTHH:mm:ss)
+     * @returns Promise resolving to NIFTY quote data or null
+     */
+    fetchNiftyQuote(params: z.infer<typeof v1_developer_groww_schemas.getGrowwNiftyQuote.query>): Promise<z.infer<typeof v1_developer_groww_schemas.getGrowwNiftyQuote.response>["data"] | null>;
+    /**
+     * Fetch NIFTY quote timeline.
+     * Given an end_datetime, returns the NIFTY quote timeline for the given date.
+     *
+     * @param end_datetime - End datetime in IST string format (YYYY-MM-DDTHH:mm:ss)
+     * @returns Promise resolving to NIFTY quote timeline data
+     */
+    fetchNiftyQuoteTimeline(end_datetime: string): Promise<z.infer<typeof v1_developer_groww_schemas.getGrowwNiftyQuoteTimeline.response>["data"]["niftyTimeline"]>;
+    /**
+     * Fetch shortlist for a specific type and datetime.
+     *
+     * @param queryParams - Query parameters for fetching shortlist
+     * @param queryParams.type - The type of shortlist (e.g., "top-gainers", "top-losers")
+     * @param queryParams.datetime - Datetime in IST string format (YYYY-MM-DDTHH:mm:ss)
+     * @returns Promise resolving to shortlist data or null
+     */
+    fetchShortlist(queryParams: z.infer<typeof v1_developer_lists_schemas.getLists.query>): Promise<z.infer<typeof v1_developer_lists_schemas.getLists.response>["data"] | null>;
+    /**
+     * Fetch shortlist persistence.
+     * Given a shortlist type and a start and end datetime,
+     * returns the list of instruments that appeared in the shortlist during the time range
+     * in descending order of appearance count.
+     *
+     * This helps identify the stocks that have been consistently appearing in the shortlist
+     * over a given period of time.
+     *
+     * @param queryParams - Query parameters for fetching shortlist persistence
+     * @param queryParams.type - The type of shortlist (e.g., "top-gainers", "top-losers")
+     * @param queryParams.start_datetime - Start datetime in IST string format (YYYY-MM-DDTHH:mm:ss)
+     * @param queryParams.end_datetime - End datetime in IST string format (YYYY-MM-DDTHH:mm:ss)
+     * @returns Promise resolving to shortlist persistence data or null
+     */
+    fetchShortlistPersistence(queryParams: z.infer<typeof v1_developer_shortlist_persistence_schemas.getShortlistPersistence.query>): Promise<z.infer<typeof v1_developer_shortlist_persistence_schemas.getShortlistPersistence.response>["data"] | null>;
+}
+
+export declare interface GanakaClientConfig {
+    /**
+     * Developer token for API authentication.
+     * If not provided, will be read from DEVELOPER_KEY environment variable.
+     */
+    developerToken?: string;
+    /**
+     * API domain base URL.
+     * If not provided, defaults to "https://api.ganaka.live".
+     * Can also be set via API_DOMAIN environment variable.
+     */
+    apiDomain?: string;
+}
+
 declare const getAvailableDatetimes: {
     query: z.ZodObject<{}, z.core.$strip>;
     response: z.ZodObject<{
@@ -601,6 +708,10 @@ declare const getLists: {
         }>;
         datetime: z.ZodOptional<z.ZodString>;
         timezone: z.ZodOptional<z.ZodString>;
+        scope: z.ZodOptional<z.ZodEnum<{
+            FULL: "FULL";
+            TOP_5: "TOP_5";
+        }>>;
     }, z.core.$strip>;
     response: z.ZodObject<{
         statusCode: z.ZodNumber;
@@ -746,6 +857,10 @@ declare const getShortlistPersistence: {
         start_datetime: z.ZodString;
         end_datetime: z.ZodString;
         timezone: z.ZodOptional<z.ZodString>;
+        scope: z.ZodOptional<z.ZodEnum<{
+            FULL: "FULL";
+            TOP_5: "TOP_5";
+        }>>;
     }, z.core.$strip>;
     response: z.ZodObject<{
         statusCode: z.ZodNumber;
@@ -777,6 +892,12 @@ declare const getShortlists: {
             TOP_GAINERS: "TOP_GAINERS";
             VOLUME_SHOCKERS: "VOLUME_SHOCKERS";
         }>;
+        scope: z.ZodOptional<z.ZodEnum<{
+            FULL: "FULL";
+            TOP_5: "TOP_5";
+        }>>;
+        takeProfitPercentage: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+        stopLossPercentage: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
     }, z.core.$strip>;
     response: z.ZodObject<{
         statusCode: z.ZodNumber;
@@ -842,6 +963,14 @@ declare const getShortlists: {
                             week_52_low: z.ZodNullable<z.ZodNumber>;
                         }, z.core.$strip>;
                     }, z.core.$strip>>>;
+                    targetPrice: z.ZodOptional<z.ZodNumber>;
+                    stopLossPrice: z.ZodOptional<z.ZodNumber>;
+                    targetAchieved: z.ZodOptional<z.ZodBoolean>;
+                    stopLossHit: z.ZodOptional<z.ZodBoolean>;
+                    timeToTargetMinutes: z.ZodOptional<z.ZodNumber>;
+                    timeToStopLossMinutes: z.ZodOptional<z.ZodNumber>;
+                    targetTimestamp: z.ZodOptional<z.ZodString>;
+                    stopLossTimestamp: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>;
             }, z.core.$strip>>;
         }, z.core.$strip>;
@@ -1000,6 +1129,69 @@ export declare interface RunContext {
     currentTimestamp: string;
 }
 
+declare const shortlistEntryWithMetricsSchema: z.ZodObject<{
+    nseSymbol: z.ZodString;
+    name: z.ZodString;
+    price: z.ZodNumber;
+    quoteData: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        status: z.ZodEnum<{
+            SUCCESS: "SUCCESS";
+            FAILURE: "FAILURE";
+        }>;
+        payload: z.ZodObject<{
+            average_price: z.ZodNullable<z.ZodNumber>;
+            bid_quantity: z.ZodNullable<z.ZodNumber>;
+            bid_price: z.ZodNullable<z.ZodNumber>;
+            day_change: z.ZodNullable<z.ZodNumber>;
+            day_change_perc: z.ZodNullable<z.ZodNumber>;
+            upper_circuit_limit: z.ZodNullable<z.ZodNumber>;
+            lower_circuit_limit: z.ZodNullable<z.ZodNumber>;
+            ohlc: z.ZodNullable<z.ZodObject<{
+                open: z.ZodNullable<z.ZodNumber>;
+                high: z.ZodNullable<z.ZodNumber>;
+                low: z.ZodNullable<z.ZodNumber>;
+                close: z.ZodNullable<z.ZodNumber>;
+            }, z.core.$strip>>;
+            depth: z.ZodNullable<z.ZodObject<{
+                buy: z.ZodArray<z.ZodObject<{
+                    price: z.ZodNullable<z.ZodNumber>;
+                    quantity: z.ZodNullable<z.ZodNumber>;
+                }, z.core.$strip>>;
+                sell: z.ZodArray<z.ZodObject<{
+                    price: z.ZodNullable<z.ZodNumber>;
+                    quantity: z.ZodNullable<z.ZodNumber>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+            high_trade_range: z.ZodNullable<z.ZodNull>;
+            implied_volatility: z.ZodNullable<z.ZodNull>;
+            last_trade_quantity: z.ZodNullable<z.ZodNumber>;
+            last_trade_time: z.ZodNullable<z.ZodNumber>;
+            low_trade_range: z.ZodNullable<z.ZodNull>;
+            last_price: z.ZodNullable<z.ZodNumber>;
+            market_cap: z.ZodNullable<z.ZodNumber>;
+            offer_price: z.ZodNullable<z.ZodNumber>;
+            offer_quantity: z.ZodNullable<z.ZodNumber>;
+            oi_day_change: z.ZodNullable<z.ZodNumber>;
+            oi_day_change_percentage: z.ZodNullable<z.ZodNumber>;
+            open_interest: z.ZodNullable<z.ZodNumber>;
+            previous_open_interest: z.ZodNullable<z.ZodNull>;
+            total_buy_quantity: z.ZodNullable<z.ZodNumber>;
+            total_sell_quantity: z.ZodNullable<z.ZodNumber>;
+            volume: z.ZodNullable<z.ZodNumber>;
+            week_52_high: z.ZodNullable<z.ZodNumber>;
+            week_52_low: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>>;
+    targetPrice: z.ZodOptional<z.ZodNumber>;
+    stopLossPrice: z.ZodOptional<z.ZodNumber>;
+    targetAchieved: z.ZodOptional<z.ZodBoolean>;
+    stopLossHit: z.ZodOptional<z.ZodBoolean>;
+    timeToTargetMinutes: z.ZodOptional<z.ZodNumber>;
+    timeToStopLossMinutes: z.ZodOptional<z.ZodNumber>;
+    targetTimestamp: z.ZodOptional<z.ZodString>;
+    stopLossTimestamp: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+
 declare const signIn: {
     body: z.ZodObject<{
         developerToken: z.ZodString;
@@ -1100,6 +1292,7 @@ declare namespace v1_dashboard_schemas {
 
 declare namespace v1_dashboard_shortlists_schemas {
     export {
+        shortlistEntryWithMetricsSchema,
         getShortlists
     }
 }