Metadata-Version: 2.4
Name: userbank
Version: 2.0.1
Summary: A Pythonic wrapper for Google Sheets based user management.
Author-email: Jordi Carrera Ventura <jordi.carrera.ventura@gmail.com>
Project-URL: Google page, https://github.com/JordiCarreraVentura/userbank
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-api-python-client
Requires-Dist: google-auth-httplib2
Requires-Dist: google-auth-oauthlib
Requires-Dist: PyYAML
Requires-Dist: python-dotenv
Dynamic: license-file

# User Bank

A Pythonic wrapper for Google Sheets based user management using the official Google API client.

## Features

- **Secure Authentication**: Check credentials (username/email and password) without listing or exposing other user records.
- **Least Privilege Access**: Operates entirely over read-only Google Sheets scopes (`spreadsheets.readonly`), guaranteeing that the client cannot write to, modify, or corrupt the user spreadsheet.
- **Zero OAuth Popups**: Uses a Google Service Account — fully automated, ideal for headless/CI/CD usage.
- **CLI Setup Wizard**: One command (`userbank`) to configure credentials and connect.
- **Environment-First Auth**: Pulls credentials from `GOOGLE_APPLICATION_CREDENTIALS` or `USER_BANK_CREDENTIALS_JSON` environment variables (or `.env` file).

## Quick Start

```bash
pip install .

# Run the setup wizard
userbank
```

The wizard will:
1. Ask for your **Google Service Account JSON key** (path or paste)
2. Ask for your **Google Sheet URL** (it saves it to `config.yml`)
3. Write `GOOGLE_APPLICATION_CREDENTIALS=keys.json` to `.env`
4. Test the connection

Then use it:

```python
from userbank import UserBank

bank = UserBank.from_config()
is_authenticated = bank.authenticate("jdoe", "securepass123", "MyApp")
```

## Manual Setup

### 1. Google Service Account

1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials).
2. Create a project (or select an existing one).
3. Create a **Service Account** → **Keys** → **Add Key** → **Create New Key (JSON)**.
4. Save the downloaded file as `keys.json` in your project root.

### 2. Enable Google Sheets API

Visit the URL below and click **Enable**:

[https://console.cloud.google.com/apis/api/sheets.googleapis.com/](https://console.cloud.google.com/apis/api/sheets.googleapis.com/)

_(The API must be enabled for the project your service account belongs to.)_

### 3. Spreadsheet

1. Create a new Google Sheet.
2. **Share** it with the service account email (found in `keys.json`).
3. Copy the sheet URL into `config.yml`:
   ```yaml
   USER_BANK_URL: https://docs.google.com/spreadsheets/d/YOUR_ID/edit
   ```

### 3. Authentication

Credentials are resolved in this order:

| # | Source | Example |
|---|---|---|
| 1 | `credentials_path` argument | `UserBank(..., credentials_path="keys.json")` |
| 2 | `credentials_info` argument | `UserBank(..., credentials_info={...})` |
| 3 | `GOOGLE_APPLICATION_CREDENTIALS` env var | path to JSON key file |
| 4 | `USER_BANK_CREDENTIALS_JSON` env var | inline JSON string |
| 5 | `.env` file | loaded automatically, then checks #3–#4 |

The simplest approach: put `GOOGLE_APPLICATION_CREDENTIALS=keys.json` in your `.env` and it just works. With the configured environment/config file, the class can be instantiated with no arguments:

```python
from userbank import UserBank

bank = UserBank()  # Implicitly resolves spreadsheet ID and credentials
```

## Usage

```python
from userbank import UserBank

bank = UserBank()

# Authenticate a user by username or email
is_authenticated = bank.authenticate(
    username_or_email="jdoe", # or "john.doe@example.com"
    password="securepassword123",
    application="MyApp"
)

if is_authenticated:
    print("User authenticated successfully!")
else:
    print("Invalid credentials or inactive user.")
```

## Spreadsheet Fields

The first row of the Google Sheet must contain these headers:

| Field | Description |
|---|---|
| `Application` | App name |
| `Email` | User's email |
| `UserName` | Login name |
| `UserPassword` | Password |
| `DateCreated` | Auto-filled on add |
| `DateLastAccess` | Auto-filled on add |
| `DateDeleted` | Soft-delete timestamp |
| `IsActive` | `TRUE` or `FALSE` |

## CLI Reference

Run `userbank` with no arguments for the interactive setup wizard.

## Installation

```bash
pip install .
```

## Publishing

`make publish`

or

```
$ python -m build
$ python -m twine upload --repository pypi dist/*
```
