diff --git a/README.md b/README.md index 7606d7b..3c88638 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,8 @@ export APERIODIC_API_KEY=your_api_key Get your API key at [aperiodic.io](https://aperiodic.io). +For [preview data](#preview-data) (`--preview`), no API key is required — the CLI uses the shared public demo key automatically. + ## Usage ``` @@ -104,6 +106,7 @@ The first argument is the metric name. Use `symbols` to list available symbols f | `--output-dir` | | Output directory for Parquet files (required) | | `--timestamp` | `exchange` | Timestamp source (`exchange` or `true`) | | `--max-concurrent` | `10` | Maximum concurrent downloads | +| `--preview` | `false` | Query the free preview dataset (no subscription; whitelisted parameters only) | ## Examples @@ -145,6 +148,21 @@ aperiodic basis \ --output-dir ./data ``` +**Preview data (no API key required):** +```bash +aperiodic ohlcv --preview \ + --exchange binance-futures \ + --symbol perpetual-BTC-USDT:USDT \ + --interval 5m \ + --start-date 2025-05-01 \ + --end-date 2025-05-31 \ + --output-dir ./data +``` + +## Preview data + +`--preview` fetches a free, curated slice of data from the preview endpoint — no subscription and no API key required (the shared public demo key is used automatically). Requests must match one of the whitelisted parameter combinations (exchange, symbol, interval, timestamp, date range) listed at [aperiodic.io/catalog](https://aperiodic.io/catalog#preview). + ## Supported Exchanges | Exchange | ID | diff --git a/cli.go b/cli.go index e293fa5..577c09c 100644 --- a/cli.go +++ b/cli.go @@ -33,14 +33,6 @@ func (c *CLI) Run(args []string) int { return 0 } - apiKey := c.Env("APERIODIC_API_KEY") - if apiKey == "" { - fmt.Fprintln(c.Stderr, "Error: APERIODIC_API_KEY environment variable not set") - return 1 - } - - client := NewAperiodicClient(apiKey) - fs := flag.NewFlagSet("aperiodic", flag.ContinueOnError) fs.SetOutput(c.Stderr) @@ -52,11 +44,25 @@ func (c *CLI) Run(args []string) int { maxConcurrentFlag := fs.Int("max-concurrent", 10, "Maximum concurrent downloads") timestampFlag := fs.String("timestamp", "exchange", "Timestamp source (exchange, true)") outputDirFlag := fs.String("output-dir", "", "Output directory for Parquet files (mandatory)") + previewFlag := fs.Bool("preview", false, "Query the free preview dataset (no subscription; whitelisted parameters only)") if err := fs.Parse(args[1:]); err != nil { return 2 } + apiKey := c.Env("APERIODIC_API_KEY") + if apiKey == "" { + if *previewFlag { + // Preview data is served against the shared demo key, so no key is required. + apiKey = DemoAPIKey + } else { + fmt.Fprintln(c.Stderr, "Error: APERIODIC_API_KEY environment variable not set (pass --preview to use the shared demo key)") + return 1 + } + } + + client := NewAperiodicClient(apiKey) + if cmd == "symbols" { return c.handleSymbols(client, *exchangeFlag) } @@ -66,7 +72,7 @@ func (c *CLI) Run(args []string) int { return 1 } - return c.handleData(client, cmd, *timestampFlag, *intervalFlag, *exchangeFlag, *symbolFlag, *startDateFlag, *endDateFlag, *maxConcurrentFlag, *outputDirFlag) + return c.handleData(client, cmd, *timestampFlag, *intervalFlag, *exchangeFlag, *symbolFlag, *startDateFlag, *endDateFlag, *maxConcurrentFlag, *outputDirFlag, *previewFlag) } func (c *CLI) printUsage() { @@ -102,7 +108,7 @@ func (c *CLI) printUsage() { fmt.Fprintln(c.Stdout, " help Show this help") fmt.Fprintln(c.Stdout) fmt.Fprintln(c.Stdout, "Environment:") - fmt.Fprintln(c.Stdout, " APERIODIC_API_KEY Aperiodic API key (required)") + fmt.Fprintln(c.Stdout, " APERIODIC_API_KEY Aperiodic API key (required, except with --preview)") fmt.Fprintln(c.Stdout) fmt.Fprintln(c.Stdout, "Flags:") fmt.Fprintln(c.Stdout, " -end-date string") @@ -115,6 +121,8 @@ func (c *CLI) printUsage() { fmt.Fprintln(c.Stdout, " Maximum concurrent downloads (default 10)") fmt.Fprintln(c.Stdout, " -output-dir string") fmt.Fprintln(c.Stdout, " Output directory for Parquet files (mandatory)") + fmt.Fprintln(c.Stdout, " -preview") + fmt.Fprintln(c.Stdout, " Query the free preview dataset (no subscription; whitelisted parameters only)") fmt.Fprintln(c.Stdout, " -start-date string") fmt.Fprintln(c.Stdout, " Start date (YYYY-MM-DD)") fmt.Fprintln(c.Stdout, " -symbol string") @@ -137,7 +145,7 @@ func (c *CLI) handleSymbols(client *AperiodicClient, exchange string) int { return 0 } -func (c *CLI) handleData(client *AperiodicClient, metric, timestamp, interval, exchange, symbol, startDate, endDate string, maxConcurrent int, outputDir string) int { +func (c *CLI) handleData(client *AperiodicClient, metric, timestamp, interval, exchange, symbol, startDate, endDate string, maxConcurrent int, outputDir string, preview bool) int { if symbol == "" { fmt.Fprintln(c.Stderr, "Error: --symbol is required") return 1 @@ -147,7 +155,7 @@ func (c *CLI) handleData(client *AperiodicClient, metric, timestamp, interval, e return 1 } - resp, err := client.FetchPresignedUrls(metric, TimestampType(timestamp), Interval(interval), exchange, symbol, startDate, endDate) + resp, err := client.FetchPresignedUrls(metric, TimestampType(timestamp), Interval(interval), exchange, symbol, startDate, endDate, preview) if err != nil { fmt.Fprintf(c.Stderr, "Error fetching file URLs: %v\n", err) return 1 diff --git a/client.go b/client.go index 79feef2..d2d64aa 100644 --- a/client.go +++ b/client.go @@ -13,6 +13,10 @@ import ( const ( DefaultBaseURL = "https://aperiodic.io/api/v1" DefaultTimeout = 60 * time.Second + + // DemoAPIKey is the shared public demo key. Preview data is served against + // it, so users can query the whitelisted preview slice without signing up. + DemoAPIKey = "DEMO-KEY" ) type APIError struct { @@ -130,8 +134,13 @@ func (c *AperiodicClient) GetSymbols(exchange string) ([]string, error) { return symResp.Symbols, nil } -func (c *AperiodicClient) FetchPresignedUrls(bucket string, timestamp TimestampType, interval Interval, exchange string, symbol string, startDate string, endDate string) (*AggregateDataResponse, error) { - u, err := url.Parse(fmt.Sprintf("%s/data/%s", c.BaseURL, bucket)) +func (c *AperiodicClient) FetchPresignedUrls(bucket string, timestamp TimestampType, interval Interval, exchange string, symbol string, startDate string, endDate string, preview bool) (*AggregateDataResponse, error) { + dataPath := fmt.Sprintf("%s/data/%s", c.BaseURL, bucket) + if preview { + dataPath = fmt.Sprintf("%s/data/preview/%s", c.BaseURL, bucket) + } + + u, err := url.Parse(dataPath) if err != nil { return nil, err } diff --git a/client_test.go b/client_test.go index 5fa168a..78d7abb 100644 --- a/client_test.go +++ b/client_test.go @@ -5,6 +5,7 @@ import ( "fmt" "io" "net/http" + "net/http/httptest" "os" "path/filepath" "strings" @@ -127,6 +128,82 @@ func TestCLI_MetricMissingOutputDir(t *testing.T) { } } +// captureCLIRequest runs the CLI against a stub server and reports the request +// path and X-API-KEY header it received. --output-dir is appended for the +// caller. APERIODIC_API_KEY is set to apiKeyEnv (use "" for an unset key). +func captureCLIRequest(t *testing.T, apiKeyEnv string, args ...string) (path, key string, exitCode int, stderr string) { + t.Helper() + + var gotPath, gotKey string + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + gotPath = r.URL.Path + gotKey = r.Header.Get("X-API-KEY") + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(`{"files": []}`)) + })) + defer srv.Close() + + t.Setenv("APERIODIC_API_URL", srv.URL) + t.Setenv("APERIODIC_API_KEY", apiKeyEnv) + + fullArgs := append(args, "-output-dir", t.TempDir()) + _, errStr, code := runCLI(fullArgs...) + return gotPath, gotKey, code, errStr +} + +var previewArgs = []string{ + "ohlcv", "-preview", + "-exchange", "binance-futures", + "-symbol", "perpetual-BTC-USDT:USDT", + "-interval", "5m", + "-start-date", "2025-05-01", + "-end-date", "2025-05-31", +} + +func TestCLI_Preview_NoAPIKeyUsesDemoKey(t *testing.T) { + path, key, code, stderr := captureCLIRequest(t, "", previewArgs...) + if code != 0 { + t.Fatalf("expected exit code 0, got %d; stderr: %s", code, stderr) + } + if key != DemoAPIKey { + t.Errorf("expected X-API-KEY %q, got %q", DemoAPIKey, key) + } + if path != "/data/preview/ohlcv" { + t.Errorf("expected preview path, got %q", path) + } +} + +func TestCLI_Preview_KeepsProvidedAPIKey(t *testing.T) { + path, key, code, stderr := captureCLIRequest(t, "real-key", previewArgs...) + if code != 0 { + t.Fatalf("expected exit code 0, got %d; stderr: %s", code, stderr) + } + if key != "real-key" { + t.Errorf("expected provided key to be used, got %q", key) + } + if path != "/data/preview/ohlcv" { + t.Errorf("expected preview path, got %q", path) + } +} + +func TestCLI_NoPreviewUsesDataPath(t *testing.T) { + args := []string{ + "ohlcv", + "-exchange", "binance-futures", + "-symbol", "perpetual-BTC-USDT:USDT", + "-interval", "5m", + "-start-date", "2025-05-01", + "-end-date", "2025-05-31", + } + path, _, code, stderr := captureCLIRequest(t, "real-key", args...) + if code != 0 { + t.Fatalf("expected exit code 0, got %d; stderr: %s", code, stderr) + } + if path != "/data/ohlcv" { + t.Errorf("expected non-preview path, got %q", path) + } +} + // Tests that always run (no API key needed) — match Python client pattern // where invalid-key tests run unconditionally and assert specific error codes.