---
title: "Getting Started with igfetchr"
output:
  rmarkdown::html_vignette:
    highlight: NULL #Disable Pandoc's highlight-style
vignette: >
  %\VignetteIndexEntry{Getting Started with igfetchr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

# Introduction

igfetchr is a beginner-friendly wrapper around the IG Trading REST API (labs.ig.com). It provides functions to authenticate, fetch markets, current prices, historical prices, account summaries, execute trades, and close sessions.

**Disclaimer:** Trading CFDs and spread bets carry a high risk of losing money. The package igfetchr is not financial advice.

# Offline / testing mode

To make examples and tests deterministic and CRAN-friendly, igfetchr supports an offline testing mode. Set the environment variable `IGFETCHR_TESTING = "true"` to return mock tokens and accept `mock_response` data frames for endpoints.

```{r testing-mode}
Sys.setenv(IGFETCHR_TESTING = "true")
library(igfetchr)
```

# Authenticate (mock)

This example uses the package's testing mode and returns a mock auth list instantly.

```{r auth}
auth <- ig_auth(
  username = "demo_user",
  password = "demo_pass",
  api_key = "demo_api_key",
  acc_type = "DEMO",
  acc_number = "ABC123"
)
auth
```

# Search markets (mock)

Use `ig_search_markets()` with `mock_response` to simulate the API returning market results.

```{r search}
mock_markets <- data.frame(
  epic = c("CS.D.USDCHF.CFD.IP"),
  instrumentName = c("USD/CHF"),
  stringsAsFactors = FALSE
)

markets <- ig_search_markets("USD/CHF", auth = auth, mock_response = mock_markets)
markets
```

# Current price (mock)

Simulate a current price response for USD/CHF.

```{r price}
mock_price <- data.frame(
  bid = 0.8500,
  offer = 0.8504,
  timestamp = Sys.time(),
  stringsAsFactors = FALSE
)
price <- ig_get_price("CS.D.USDCHF.CFD.IP", auth = auth, mock_response = mock_price)
price
```

# Historical prices (mock)

Simulate historical OHLC data for USD/CHF.

```{r historical}
mock_hist <- data.frame(
  snapshotTime = as.character(Sys.Date() - 2:0),
  open = c(0.8500, 0.8550, 0.8520),
  high = c(0.8520, 0.8570, 0.8540),
  low = c(0.8480, 0.8530, 0.8500),
  close = c(0.8510, 0.8540, 0.8530),
  stringsAsFactors = FALSE
)

hist <- ig_get_historical(
  epic = "CS.D.USDCHF.CFD.IP",
  from = Sys.Date() - 2,
  to = Sys.Date(),
  resolution = "D",
  auth = auth,
  mock_response = mock_hist
)
hist
```

# Accounts (mock)

Simulate account summary retrieval.

```{r accounts}
mock_accounts <- data.frame(
  accountId = "ACCT123",
  balance = 10000,
  preferred = TRUE,
  stringsAsFactors = FALSE
)
accounts <- ig_get_accounts(auth = auth, mock_response = mock_accounts)
accounts
```

# Execute Trade (mock)

Simulate executing a trade for USD/CHF.

```{r trade}
mock_trade <- data.frame(
  dealId = "DIXXXX",
  dealReference = "REF123",
  status = "OPEN",
  stringsAsFactors = FALSE
)
trade <- ig_execute_trade(
  epic = "CS.D.USDCHF.CFD.IP",
  direction = "BUY",
  size = 1.0,
  auth = auth,
  mock_response = mock_trade
)
trade
```

# Close Session (mock)

Close the session.

```{r logout}
ig_close_session(auth, mock_response = TRUE)
Sys.unsetenv("IGFETCHR_TESTING")
```

# Notes

- The vignette uses the built-in testing mode so it runs quickly and without network, satisfying CRAN checks.
- Real API usage requires a free API key from https://labs.ig.com and valid credentials. Replace the mock usage above with real calls and remove the testing environment variable when running live.