Metadata-Version: 2.4
Name: triangle-api
Version: 0.1.0
Summary: Unofficial Python wrapper for Canadian Tire Triangle Mastercard API
Home-page: https://github.com/diogobas/triangle-api
Author: Diogo Bastos
Author-email: seu-email@exemplo.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: playwright>=1.40.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Triangle Mastercard API (Unofficial) 🇨🇦

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/diogobas/triangle-api/graphs/commit-activity)

Um wrapper em Python para a API privada do **Triangle Mastercard (Canadian Tire Financial Services)**. 

Este projeto realiza a engenharia reversa do portal web oficial para extrair informações de saldo, limites e transações, permitindo a integração dos seus dados financeiros em seus próprios aplicativos, bots ou planilhas.

---

## ⚠️ Aviso Legal (Disclaimer)

**Este projeto não é afiliado, mantido, autorizado, endossado ou patrocinado pela Canadian Tire Financial Services (CTFS) ou qualquer uma de suas afiliadas.**

Este é um software independente para fins educacionais e de uso pessoal. O uso de automação para acessar contas bancárias pode violar os Termos de Serviço da instituição. Use com responsabilidade e por sua conta e risco.

---

## ✨ Funcionalidades

- [x] **Autenticação Automatizada**: Realiza o login via Playwright lidando com proteção de bots.
- [x] **Suporte a MFA**: Detecta e solicita o código de SMS/Segurança via terminal.
- [x] **Persistência de Sessão**: Salva cookies localmente para evitar logins constantes e reduzir o risco de bloqueio.
- [x] **Resumo da Conta**: Saldo atual, crédito disponível, limite total e data de vencimento.
- [ ] **Histórico de Transações**: (Em desenvolvimento)
- [ ] **Triangle Rewards**: Saldo de Canadian Tire Money (Em desenvolvimento)

---

## 🚀 Instalação

1. Clone o repositório:
`git clone https://github.com/diogobas/triangle-api.git
cd triangle-api`

2.  Instale as dependências: `pip install -r requirements.txt`

3.  Instale o navegador necessário pelo Playwright: `playwright install chromium`

💻 Exemplo de Uso

```
from triangle_api.client 
import TriangleClient
import os

# Recomenda-se usar variáveis de ambiente para segurança
USER = "seu_email@exemplo.com"
PASSWORD = "sua_senha_secreta"

# Instancia o cliente
client = TriangleClient(username=USER, password=PASSWORD)

# Realiza o login (abre o navegador na primeira vez, usa cookies nas próximas)
# headless=False permite ver o navegador operando
data = client.login(headless=True)

print(f"Saldo Atual: $ {client.get_balance()}")
print(f"Crédito Disponível: $ {data.get('availableCreditAmt')}")
```

🔒 Segurança e Persistência

Para evitar que o banco suspeite de múltiplos logins, este wrapper utiliza o
recurso storage_state do Playwright.

  - Após o primeiro login bem-sucedido, um arquivo auth_state.json é criado.
  - Nas próximas execuções, o script tentará usar esses cookies para acessar o
    Dashboard diretamente.
  - Atenção: Nunca envie o arquivo auth_state.json para o GitHub (ele já está no
    .gitignore).

🛠️ Desenvolvimento

Se você quiser contribuir para o projeto mapeando novos endpoints (como
transações ou ofertas), siga estes passos:

1.  Faça o login no site da CTFS com o modo Inspecionar (F12) aberto.
2.  Filtre por chamadas XHR/Fetch.
3.  Procure por endpoints como retrieveTransactions ou retrieveLoyalty.
4.  Mapeie o JSON de resposta na classe TriangleClient.
