@ganaka/sdk 1.6.0 → 1.8.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

@@ -79,6 +79,16 @@ declare const deleteRun: {
     }, z.core.$strip>;
 };
 
+declare const fetchAvailableDates: ({ developerToken, apiDomain, runId, currentTimestamp, currentTimezone, }: {
+    developerToken: string;
+    apiDomain: string;
+    runId: string | null;
+    currentTimestamp: string;
+    currentTimezone?: string;
+}) => () => Promise<default_2.infer<typeof v1_developer_available_dates_schemas.getAvailableDates.response>["data"]>;
+
+export declare type FetchAvailableDatesResponse = Awaited<ReturnType<ReturnType<typeof fetchAvailableDates>>>;
+
 declare const fetchCandles: ({ developerToken, apiDomain, runId, currentTimestamp, currentTimezone, }: {
     developerToken: string;
     apiDomain: string;
@@ -89,6 +99,16 @@ declare const fetchCandles: ({ developerToken, apiDomain, runId, currentTimestam
 
 export declare type FetchCandlesResponse = Awaited<ReturnType<ReturnType<typeof fetchCandles>>>;
 
+declare const fetchHolidays: ({ developerToken, apiDomain, runId, currentTimestamp, currentTimezone, }: {
+    developerToken: string;
+    apiDomain: string;
+    runId: string | null;
+    currentTimestamp: string;
+    currentTimezone?: string;
+}) => () => Promise<default_2.infer<typeof v1_developer_holidays_schemas.getHolidays.response>["data"]>;
+
+export declare type FetchHolidaysResponse = Awaited<ReturnType<ReturnType<typeof fetchHolidays>>>;
+
 declare const fetchNiftyQuote: ({ developerToken, apiDomain, runId, currentTimestamp, currentTimezone, }: {
     developerToken: string;
     apiDomain: string;
@@ -178,6 +198,141 @@ 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>;
+    /**
+     * Fetch available dates with timestamps.
+     * Returns which dates have data available, grouped by date with all timestamps for each date.
+     *
+     * @returns Promise resolving to available dates data with dates and timestamps
+     */
+    fetchAvailableDates(): Promise<z.infer<typeof v1_developer_available_dates_schemas.getAvailableDates.response>["data"]>;
+    /**
+     * Fetch market holidays.
+     * Returns all dates marked as market holidays.
+     *
+     * @returns Promise resolving to holidays data
+     */
+    fetchHolidays(): Promise<z.infer<typeof v1_developer_holidays_schemas.getHolidays.response>["data"]>;
+}
+
+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 getAvailableDates: {
+    query: z.ZodObject<{}, z.core.$strip>;
+    response: z.ZodObject<{
+        statusCode: z.ZodNumber;
+        message: z.ZodString;
+        data: z.ZodObject<{
+            dates: z.ZodArray<z.ZodObject<{
+                date: z.ZodString;
+                timestamps: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+};
+
 declare const getAvailableDatetimes: {
     query: z.ZodObject<{}, z.core.$strip>;
     response: z.ZodObject<{
@@ -593,6 +748,21 @@ declare const getGrowwToken: {
     }, z.core.$strip>;
 };
 
+declare const getHolidays: {
+    response: z.ZodObject<{
+        statusCode: z.ZodNumber;
+        message: z.ZodString;
+        data: z.ZodObject<{
+            holidays: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                date: z.ZodString;
+                createdAt: z.ZodCoercedDate<unknown>;
+                updatedAt: z.ZodCoercedDate<unknown>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+};
+
 declare const getLists: {
     query: z.ZodObject<{
         type: z.ZodEnum<{
@@ -1015,6 +1185,20 @@ export declare interface RunContext {
      * over a given period of time.
      */
     fetchShortlistPersistence: ReturnType<typeof fetchShortlistPersistence>;
+    /**
+     * Fetch available dates with timestamps.
+     * Returns which dates have data available, grouped by date with all timestamps for each date.
+     *
+     * @returns Available dates data with dates and timestamps
+     */
+    fetchAvailableDates: ReturnType<typeof fetchAvailableDates>;
+    /**
+     * Fetch market holidays.
+     * Returns all dates marked as market holidays.
+     *
+     * @returns Holidays data
+     */
+    fetchHolidays: ReturnType<typeof fetchHolidays>;
     /**
      * Current timestamp in IST string format (YYYY-MM-DDTHH:mm:ss)
      * for every loop iteration
@@ -1190,6 +1374,12 @@ declare namespace v1_dashboard_shortlists_schemas {
     }
 }
 
+declare namespace v1_developer_available_dates_schemas {
+    export {
+        getAvailableDates
+    }
+}
+
 declare namespace v1_developer_groww_schemas {
     export {
         growwHistoricalCandlesSchema,
@@ -1202,6 +1392,12 @@ declare namespace v1_developer_groww_schemas {
     }
 }
 
+declare namespace v1_developer_holidays_schemas {
+    export {
+        getHolidays
+    }
+}
+
 declare namespace v1_developer_lists_schemas {
     export {
         listSchema,