@moonhr/sheets-client 0.1.0 → 0.1.1

package/README.md

@@ -1,15 +1,207 @@
 # @moonhr/sheets-client
 
+[English](#english) | [한국어](#한국어)
+
+---
+
+## English
+
+A lightweight Google Sheets client that eliminates the authentication and CRUD boilerplate when using Sheets as a form data store.  
+Includes service account auth, row append/query/update, and phone number cell formatting.
+
+### Installation
+
+```bash
+npm install @moonhr/sheets-client
+```
+
+### Prerequisites
+
+1. Create a service account in [Google Cloud Console](https://console.cloud.google.com/) and download the JSON key.
+2. Share the target spreadsheet with the service account email as an **Editor**.
+3. Set the following environment variables.
+
+```env
+GOOGLE_SERVICE_ACCOUNT_KEY={"client_email":"...","private_key":"..."}
+GOOGLE_SHEETS_SPREADSHEET_ID=1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms
+GOOGLE_SHEETS_SHEET_NAME=Sheet1
+```
+
+### Basic Usage
+
+```typescript
+import { createSheetsClient } from '@moonhr/sheets-client'
+
+const client = createSheetsClient({
+  serviceAccountKey: process.env.GOOGLE_SERVICE_ACCOUNT_KEY,
+  spreadsheetId: process.env.GOOGLE_SHEETS_SPREADSHEET_ID,
+  sheetName: process.env.GOOGLE_SHEETS_SHEET_NAME,
+})
+```
+
+### API
+
+#### `appendRow(values, range?)`
+
+Appends data to the last row of the sheet.
+
+```typescript
+await client.appendRow(['2024-01-01', 'John Doe', 'Acme Corp', '01012345678'])
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `values` | `string[]` | — | Array of cell values |
+| `range` | `string` | `'A:Z'` | Target range |
+
+---
+
+#### `getRows(range?)`
+
+Returns all rows in the specified range. Each cell is a trimmed string.
+
+```typescript
+const rows = await client.getRows('A:E')
+// [['Header1', 'Header2', ...], ['Value1', 'Value2', ...], ...]
+```
+
+---
+
+#### `findRow(matcher, options?)`
+
+Returns the first row matching the condition, or `null` if not found.
+
+**Match by column index (0-based)**
+
+```typescript
+const result = await client.findRow({ 1: 'John Doe', 2: 'Acme Corp' })
+```
+
+Performs a trim + lowercase comparison on both sides.
+
+**Match with a custom function**
+
+Use this when you need numeric comparison, e.g. for phone numbers.
+
+```typescript
+import { digitsOnly } from '@moonhr/sheets-client'
+
+const result = await client.findRow((row) => {
+  return row[1].trim().toLowerCase() === 'john doe' &&
+         digitsOnly(row[3]) === digitsOnly('010-1234-5678')
+})
+```
+
+**Return value**
+
+```typescript
+{
+  rowIndex: number   // 1-based sheet row number — pass directly to updateRow
+  values: string[]   // Array of cell values in that row
+}
+```
+
+**options**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `range` | `string` | `'A:Z'` | Search range |
+| `skipHeader` | `boolean` | `true` | Whether to skip the first (header) row |
+
+---
+
+#### `updateRow(rowIndex, values, startCol?)`
+
+Updates cells in a specific row.
+
+```typescript
+// Use the rowIndex returned by findRow directly
+await client.updateRow(result.rowIndex, ['John Doe', 'New Corp', '01099998888'], 'B')
+// → Updates range B{rowIndex}:D{rowIndex}
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `rowIndex` | `number` | — | Sheet row number (2 or greater) |
+| `values` | `string[]` | — | Array of replacement cell values |
+| `startCol` | `string` | `'A'` | Starting column letter |
+
+---
+
+### Utilities
+
+```typescript
+import { toTextCell, digitsOnly, stripQuotes } from '@moonhr/sheets-client'
+```
+
+| Function | Description | Example |
+|---|---|---|
+| `toTextCell(value)` | Forces a phone number to be saved as text in Sheets (prevents auto-conversion to number) | `'01012345678'` → `"'01012345678"` |
+| `digitsOnly(value)` | Extracts digits only (for phone number comparison) | `'010-1234-5678'` → `'01012345678'` |
+| `stripQuotes(value)` | Removes wrapping quotes from environment variable values | `'"Sheet1"'` → `'Sheet1'` |
+
+### Real-world Example — RSVP Form
+
+```typescript
+import { createSheetsClient, toTextCell, digitsOnly } from '@moonhr/sheets-client'
+
+const client = createSheetsClient({
+  serviceAccountKey: process.env.GOOGLE_SERVICE_ACCOUNT_KEY,
+  spreadsheetId: process.env.GOOGLE_SHEETS_SPREADSHEET_ID,
+  sheetName: process.env.GOOGLE_SHEETS_SHEET_NAME,
+})
+
+// Submit registration
+await client.appendRow([
+  new Date().toISOString(),
+  'John Doe',
+  'Acme Corp',
+  toTextCell('01012345678'),
+  'john@example.com',
+  'Agreed',
+])
+
+// Look up registration
+const found = await client.findRow((row) =>
+  row[1].trim() === 'John Doe' &&
+  digitsOnly(row[3]) === '01012345678'
+)
+
+// Update registration
+if (found) {
+  await client.updateRow(
+    found.rowIndex,
+    ['John Doe', 'New Corp', toTextCell('01099998888'), 'new@example.com'],
+    'B'
+  )
+}
+```
+
+### Build
+
+```bash
+npm run build   # generate dist/
+npm run dev     # watch mode
+```
+
+### License
+
+MIT
+
+---
+
+## 한국어
+
 Google Sheets를 폼 데이터 저장소로 사용할 때 필요한 인증·CRUD 보일러플레이트를 제거해주는 경량 클라이언트입니다.  
 서비스 계정 인증, 행 추가/조회/수정, 전화번호 셀 포맷 처리를 포함합니다.
 
-## 설치
+### 설치
 
 ```bash
 npm install @moonhr/sheets-client
 ```
 
-## 사전 준비
+### 사전 준비
 
 1. [Google Cloud Console](https://console.cloud.google.com/)에서 서비스 계정을 생성하고 JSON 키를 발급합니다.
 2. 해당 서비스 계정 이메일을 대상 스프레드시트에 **편집자** 권한으로 공유합니다.
@@ -21,7 +213,7 @@ GOOGLE_SHEETS_SPREADSHEET_ID=1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms
 GOOGLE_SHEETS_SHEET_NAME=Sheet1
 ```
 
-## 기본 사용법
+### 기본 사용법
 
 ```typescript
 import { createSheetsClient } from '@moonhr/sheets-client'
@@ -33,9 +225,9 @@ const client = createSheetsClient({
 })
 ```
 
-## API
+### API
 
-### `appendRow(values, range?)`
+#### `appendRow(values, range?)`
 
 시트 마지막 행에 데이터를 추가합니다.
 
@@ -50,7 +242,7 @@ await client.appendRow(['2024-01-01', '홍길동', '회사명', '01012345678'])
 
 ---
 
-### `getRows(range?)`
+#### `getRows(range?)`
 
 지정 범위의 모든 행을 반환합니다. 각 셀은 trim된 문자열입니다.
 
@@ -61,7 +253,7 @@ const rows = await client.getRows('A:E')
 
 ---
 
-### `findRow(matcher, options?)`
+#### `findRow(matcher, options?)`
 
 조건에 맞는 첫 번째 행을 반환합니다. 없으면 `null`.
 
@@ -104,7 +296,7 @@ const result = await client.findRow((row) => {
 
 ---
 
-### `updateRow(rowIndex, values, startCol?)`
+#### `updateRow(rowIndex, values, startCol?)`
 
 특정 행의 셀을 업데이트합니다.
 
@@ -122,7 +314,7 @@ await client.updateRow(result.rowIndex, ['홍길동', '새회사', '01099998888'
 
 ---
 
-## 유틸리티
+### 유틸리티
 
 ```typescript
 import { toTextCell, digitsOnly, stripQuotes } from '@moonhr/sheets-client'
@@ -134,7 +326,7 @@ import { toTextCell, digitsOnly, stripQuotes } from '@moonhr/sheets-client'
 | `digitsOnly(value)` | 숫자만 추출 (전화번호 비교용) | `'010-1234-5678'` → `'01012345678'` |
 | `stripQuotes(value)` | 환경변수 래핑 따옴표 제거 | `'"Sheet1"'` → `'Sheet1'` |
 
-## 실사용 예시 — RSVP 폼
+### 실사용 예시 — RSVP 폼
 
 ```typescript
 import { createSheetsClient, toTextCell, digitsOnly } from '@moonhr/sheets-client'
@@ -171,13 +363,13 @@ if (found) {
 }
 ```
 
-## 빌드
+### 빌드
 
 ```bash
 npm run build   # dist/ 생성
 npm run dev     # watch 모드
 ```
 
-## 라이선스
+### 라이선스
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moonhr/sheets-client",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Google Sheets client for form-based data collection",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -12,7 +12,9 @@
       "require": "./dist/index.js"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch"
@@ -24,6 +26,10 @@
     "tsup": "^8.0.0",
     "typescript": "^5.0.0"
   },
-  "keywords": ["google-sheets", "spreadsheet", "form"],
+  "keywords": [
+    "google-sheets",
+    "spreadsheet",
+    "form"
+  ],
   "license": "MIT"
 }