Metadata-Version: 2.4
Name: ios-deposit
Version: 0.1.1
Summary: 아이폰 단축어 카카오뱅크 입금 문자 수신 서버
Author: mickievely
License: MIT
Project-URL: Homepage, https://github.com/mickievely/ios-deposit
Project-URL: Repository, https://github.com/mickievely/ios-deposit
Keywords: ios,shortcuts,kakaobank,deposit,webhook
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.9
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://img.shields.io/badge/ios--deposit-입금%20수신%20서버-111111?style=for-the-badge" alt="ios-deposit" />
</p>

<p align="center">
  아이폰이 카카오뱅크 입금 알림을 받으면,<br/>
  디스코드 자판기 · 웹 자판기 · 쇼핑몰 · 자동화 서버로 넘깁니다.
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.9+-3776AB?logo=python&logoColor=white" alt="Python 3.9+" />
  <img src="https://img.shields.io/badge/pip-ios--deposit-3775A9?logo=pypi&logoColor=white" alt="pip" />
  <img src="https://img.shields.io/badge/카카오뱅크-3333%20%2F%207777-FFCD00?logo=kakaotalk&logoColor=000" alt="KakaoBank" />
</p>

> [!IMPORTANT]
> **카카오뱅크 `3333` 계좌, `7777` 계좌만** 됩니다.<br/>
> 국민·신한 같은 다른 은행, 다른 카카오뱅크 계좌는 안 됩니다.

```
아이폰 단축어  →  ios-deposit  →  디스코드 봇 / 웹 자판기 / 쇼핑몰 / 아무 HTTP
```

컴퓨터(또는 VPS)에서 이 프로그램을 켜 두고,
아이폰 단축어가 입금 알림을 여기로 보내면 됩니다.

---

## 1. 실행

```bash
pip install ios-deposit
ios-deposit
```

소스 받아서 켤 때는 패키지 없이 이렇게도 됩니다.

```bash
python app.py
```

처음 켜면 `config.json` 이 자동으로 생깁니다.
그 파일을 열어서 아래만 고치면 됩니다.

```
app.py              백엔드 실행
ios_deposit/        모듈
  app.py            서버
  auth/             키 · 요청 제한
  router/           경로
  data/             저장
  parse/            입금 문자
  webhook/          다른 서버로 전달
  config/           설정
examples/           봇 · 웹자판기 예시
```

---

## 2. 충전 전용 키

주소를 아는 사람이 아무거나 보내면 안 되니까, **이 프로그램용 키를 하나 만드세요.**
디스코드 봇 토큰이랑 같은 거 쓰지 마세요. 32자 정도 랜덤이면 됩니다.

`config.json`

```json
{
  "api_key": "여기-충전전용-키"
}
```

아이폰 단축어에도 **똑같은 값**을 헤더로 넣습니다.

```
X-API-Key: 여기-충전전용-키
```

키를 여러 번 틀리면 그 아이피는 잠시 막힙니다.

---

## 3. 아이폰에서 어디로 보내나

이 프로그램은 `8088` 포트에서 기다립니다.

**공인 아이피로 쓸 때**

```
POST http://서버아이피:8088/charge
```

**도메인이 있을 때** — `config.json` 에 도메인만 적으면 됩니다.

```json
{
  "domain": "https://pay.example.com"
}
```

단축어 주소는 이렇게 쓰면 됩니다.

```
POST https://pay.example.com/charge
```

보낼 내용 예시

```json
{
  "message": "[카카오뱅크]\n입금 10,000원\n홍길동\n잔액 123,456원"
}
```

헤더는 이거 두 개입니다.

```
Content-Type: application/json
X-API-Key: 여기-충전전용-키
```

잘 켜져 있는지는 브라우저에서 열어보면 됩니다.

```
http://서버아이피:8088/health
```

집 컴퓨터로 쓸 때는 공유기에서 `8088` 포트를 열어줘야 아이폰이 밖에서 들어옵니다.

---

## 4. 도메인 쓰는 사람

아이피 대신 `pay.example.com` 같은 주소를 쓰고 싶으면:

1. 도메인을 서버 아이피로 연결합니다.
2. Cloudflare나 nginx에서 `80` / `443` 을 이 프로그램(`127.0.0.1:8088`)으로 넘깁니다.
3. `config.json` 의 `domain` 에 그 주소를 넣습니다.

이 프로그램 자체는 계속 `8088` 에서 받고, 도메인은 그 앞단에서만 붙이면 됩니다.

nginx 예시

```nginx
server {
    listen 443 ssl;
    server_name pay.example.com;

    location / {
        proxy_pass http://127.0.0.1:8088;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }
}
```

주소를 `https://pay.example.com/deposit/charge` 처럼 쓰고 싶으면
`base_path` 를 `/deposit` 으로 두면 됩니다.

---

## 5. 잘 됐는지

성공하면 이런 답이 옵니다.

```json
{"ok": true, "parsed": {"amount": 10000, "depositor": "홍길동"}}
```

카카오뱅크가 아니거나 지원 계좌가 아니면

```json
{"ok": false, "error": "카카오뱅크 3333 / 7777 계좌만 지원합니다"}
```

같은 문자가 또 오면

```json
{"ok": false, "duplicate": true}
```

받은 원문은 여기 쌓입니다.

```
data/charge_api/received_YYYYMMDD_HHMMSS.txt
data/charge_api/request_log.txt
```

---

## 6. 웹 자판기 · 웹서비스 · 자동화에 붙이기

HTTP로 POST 받을 수 있으면 됩니다. 파이썬 봇이든, PHP 웹자판기든, Node 쇼핑몰이든 같습니다.

`config.json` 에 받을 주소만 넣습니다.

```json
{
  "webhook_url": "https://내사이트.com/api/charge/sms",
  "webhook_api_key": "받을쪽에서-검사할-키"
}
```

로컬에서 테스트할 때

```json
{
  "webhook_url": "http://127.0.0.1:5000/api/charge/sms"
}
```

입금이 오면 그 주소로 이걸 보냅니다.

```json
{
  "message": "원본 문자 전체",
  "parsed": {"amount": 10000, "depositor": "홍길동"},
  "received_at": "2026-06-08T12:34:56"
}
```

받는 쪽에서 `{"ok": true}` 또는 `{"matched": true}` 를 주면 충전 성공으로 처리합니다.

파이썬 웹 수신 예시는 `examples/web_receiver.py` 입니다.

```bash
python examples/web_receiver.py
```

PHP면 대충 이렇게 받으면 됩니다.

```php
<?php
$body = json_decode(file_get_contents("php://input"), true);
$amount = $body["parsed"]["amount"] ?? 0;
$name = $body["parsed"]["depositor"] ?? "";
// 여기서 주문 매칭
echo json_encode(["ok" => true]);
```

Node면

```js
app.post("/api/charge/sms", (req, res) => {
  const { amount, depositor } = req.body.parsed || {};
  // 여기서 주문 매칭
  res.json({ ok: true });
});
```

---

## 7. 다른 프로젝트에서 같이 쓰기

폴더 복사할 필요 없습니다. 그 프로젝트에서 설치만 하면 됩니다.

받은 버전 그대로 쓸 때

```bash
pip install ios-deposit
```

이 저장소 코드 고치면서 같이 작업할 때. `-e` 로 설치하면 여기 파일 수정한 게 다른 프로젝트에 바로 반영됩니다.

```bash
pip install -e ../ios-deposit
```

경로는 이 폴더 위치로 바꾸면 됩니다.

자판기 봇에 붙이기

```python
from ios_deposit import attach_bot

bot._charge_api_loop = bot.loop
attach_bot(bot, process_charge_message_content, api_key="충전전용키")
```

직접 함수로 받기

```python
from ios_deposit import attach, parse_deposit_message

def on_charge(message: str):
    parsed = parse_deposit_message(message)
    if not parsed:
        return False, None, "no match"
    return True, None, f"{parsed['amount']:,}원"

attach(on_charge, port=8088, api_key="충전전용키", loop=bot.loop)
```

예시는 `examples/use_in_other_project.py` 에 있습니다.

---

## config.json 항목

자주 만지는 것만 보면 됩니다. 나머지는 비워둬도 됩니다.

| 이름 | 뭐 하는 거 |
|---|---|
| `api_key` | 충전 전용 키. 단축어랑 같아야 함 |
| `domain` | 도메인 쓸 때 주소. 예: `https://pay.example.com` |
| `webhook_url` | 다른 프로그램으로 넘길 주소 |
| `port` | 이 프로그램 포트. 기본 `8088` |
| `host` | 보통 `0.0.0.0` 그대로 |
| `https` | 도메인 쓸 때 https 로 보여줄지 |
| `base_path` | 도메인 뒤에 `/deposit` 같은 경로를 붙일 때 |
| `webhook_api_key` | 넘기는 쪽에 키를 보내야 할 때 |
| `data_dir` | 수신 기록 폴더 |

`config.json` 은 깃에 안 올라갑니다. 키 넣은 채로 올리지 마세요.

같은 역할인 경로: `/charge` · `/api/charge/sms` · `/api/ios/charge`

---

## pip에 올리기

남들이 `pip install ios-deposit` 하게 하려면 [pypi.org](https://pypi.org) 계정 만들고, 아래를 한 번만 하면 됩니다.

[Publishing 설정](https://pypi.org/manage/account/publishing/) 에서 **대기 중인 게시자** 에 이걸 넣습니다.

| 칸 | 값 |
|---|---|
| PyPI 프로젝트 이름 | `ios-deposit` |
| 소유자 | `mickievely` |
| 저장소 이름 | `ios-deposit` |
| Workflow 이름 | `publish.yml` |
| 환경 이름 | `pypi` |

저장한 뒤 GitHub 저장소 **Settings → Environments** 에서 `pypi` 환경을 만들고, **Releases** 에서 태그 `v0.1.0` 을 올리면 Actions가 PyPI에 올립니다.

올리면 사용자는 이렇게 씁니다.

```bash
pip install ios-deposit
ios-deposit
```

버전 올릴 때는 `pyproject.toml` 의 `version` 을 바꾸고 새 Release 를 만들면 됩니다.
