@moonhr/sheets-client 0.1.0

package/README.md

@@ -0,0 +1,183 @@
+# @moonhr/sheets-client
+
+Google Sheets를 폼 데이터 저장소로 사용할 때 필요한 인증·CRUD 보일러플레이트를 제거해주는 경량 클라이언트입니다.  
+서비스 계정 인증, 행 추가/조회/수정, 전화번호 셀 포맷 처리를 포함합니다.
+
+## 설치
+
+```bash
+npm install @moonhr/sheets-client
+```
+
+## 사전 준비
+
+1. [Google Cloud Console](https://console.cloud.google.com/)에서 서비스 계정을 생성하고 JSON 키를 발급합니다.
+2. 해당 서비스 계정 이메일을 대상 스프레드시트에 **편집자** 권한으로 공유합니다.
+3. 환경변수를 설정합니다.
+
+```env
+GOOGLE_SERVICE_ACCOUNT_KEY={"client_email":"...","private_key":"..."}
+GOOGLE_SHEETS_SPREADSHEET_ID=1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms
+GOOGLE_SHEETS_SHEET_NAME=Sheet1
+```
+
+## 기본 사용법
+
+```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?)`
+
+시트 마지막 행에 데이터를 추가합니다.
+
+```typescript
+await client.appendRow(['2024-01-01', '홍길동', '회사명', '01012345678'])
+```
+
+| 파라미터 | 타입 | 기본값 | 설명 |
+|---|---|---|---|
+| `values` | `string[]` | — | 셀 값 배열 |
+| `range` | `string` | `'A:Z'` | 추가 범위 |
+
+---
+
+### `getRows(range?)`
+
+지정 범위의 모든 행을 반환합니다. 각 셀은 trim된 문자열입니다.
+
+```typescript
+const rows = await client.getRows('A:E')
+// [['헤더1', '헤더2', ...], ['값1', '값2', ...], ...]
+```
+
+---
+
+### `findRow(matcher, options?)`
+
+조건에 맞는 첫 번째 행을 반환합니다. 없으면 `null`.
+
+**컬럼 인덱스로 매칭 (0-based)**
+
+```typescript
+const result = await client.findRow({ 1: '홍길동', 2: '회사명' })
+```
+
+양쪽 trim + 소문자 비교를 수행합니다.
+
+**커스텀 함수로 매칭**
+
+전화번호처럼 숫자 비교가 필요한 경우에 사용합니다.
+
+```typescript
+import { digitsOnly } from '@moonhr/sheets-client'
+
+const result = await client.findRow((row) => {
+  return row[1].trim().toLowerCase() === '홍길동' &&
+         digitsOnly(row[3]) === digitsOnly('010-1234-5678')
+})
+```
+
+**반환값**
+
+```typescript
+{
+  rowIndex: number   // 시트 행 번호 (1-based) — updateRow에 그대로 사용
+  values: string[]   // 해당 행의 셀 값 배열
+}
+```
+
+**options**
+
+| 옵션 | 타입 | 기본값 | 설명 |
+|---|---|---|---|
+| `range` | `string` | `'A:Z'` | 검색 범위 |
+| `skipHeader` | `boolean` | `true` | 첫 번째 행(헤더) 건너뜀 여부 |
+
+---
+
+### `updateRow(rowIndex, values, startCol?)`
+
+특정 행의 셀을 업데이트합니다.
+
+```typescript
+// findRow가 반환한 rowIndex를 그대로 사용
+await client.updateRow(result.rowIndex, ['홍길동', '새회사', '01099998888'], 'B')
+// → B{rowIndex}:D{rowIndex} 범위를 업데이트
+```
+
+| 파라미터 | 타입 | 기본값 | 설명 |
+|---|---|---|---|
+| `rowIndex` | `number` | — | 시트 행 번호 (2 이상) |
+| `values` | `string[]` | — | 교체할 셀 값 배열 |
+| `startCol` | `string` | `'A'` | 시작 열 문자 |
+
+---
+
+## 유틸리티
+
+```typescript
+import { toTextCell, digitsOnly, stripQuotes } from '@moonhr/sheets-client'
+```
+
+| 함수 | 설명 | 예시 |
+|---|---|---|
+| `toTextCell(value)` | 전화번호를 시트에 텍스트로 강제 저장 (숫자 자동변환 방지) | `'01012345678'` → `"'01012345678"` |
+| `digitsOnly(value)` | 숫자만 추출 (전화번호 비교용) | `'010-1234-5678'` → `'01012345678'` |
+| `stripQuotes(value)` | 환경변수 래핑 따옴표 제거 | `'"Sheet1"'` → `'Sheet1'` |
+
+## 실사용 예시 — RSVP 폼
+
+```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,
+})
+
+// 신청 접수
+await client.appendRow([
+  new Date().toISOString(),
+  '홍길동',
+  '(주)회사',
+  toTextCell('01012345678'),
+  'hong@example.com',
+  '동의',
+])
+
+// 신청 조회
+const found = await client.findRow((row) =>
+  row[1].trim() === '홍길동' &&
+  digitsOnly(row[3]) === '01012345678'
+)
+
+// 신청 수정
+if (found) {
+  await client.updateRow(
+    found.rowIndex,
+    ['홍길동', '새회사', toTextCell('01099998888'), 'new@example.com'],
+    'B'
+  )
+}
+```
+
+## 빌드
+
+```bash
+npm run build   # dist/ 생성
+npm run dev     # watch 모드
+```
+
+## 라이선스
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,62 @@
+interface ServiceAccountKey {
+    client_email: string;
+    private_key: string;
+}
+interface SheetsClientConfig {
+    /** 서비스 계정 JSON (문자열 또는 객체) */
+    serviceAccountKey: string | ServiceAccountKey;
+    spreadsheetId: string;
+    sheetName: string;
+}
+interface FindResult {
+    /** 시트의 실제 행 번호 (1-based, 헤더 포함) — updateRow에 그대로 사용 가능 */
+    rowIndex: number;
+    values: string[];
+}
+type RowMatcher = Record<number, string> | ((row: string[], rowIndex: number) => boolean);
+
+declare class SheetsClient {
+    private readonly spreadsheetId;
+    private readonly sheetName;
+    private readonly serviceAccountKey;
+    constructor(config: SheetsClientConfig);
+    private sheets;
+    private range;
+    /** 시트 끝에 행 추가 */
+    appendRow(values: string[], range?: string): Promise<void>;
+    /** 지정 범위의 모든 행 반환 (각 셀은 trim된 문자열) */
+    getRows(range?: string): Promise<string[][]>;
+    /**
+     * 조건에 맞는 첫 번째 행을 반환.
+     *
+     * matcher가 Record이면 { [컬럼인덱스]: 기대값 } — 양쪽 trim+소문자 비교
+     * matcher가 함수이면 (row, rowIndex) => boolean — 커스텀 비교 가능
+     *
+     * @param skipHeader true이면 첫 번째 행(헤더)을 건너뜀 (기본값: true)
+     */
+    findRow(matcher: RowMatcher, options?: {
+        range?: string;
+        skipHeader?: boolean;
+    }): Promise<FindResult | null>;
+    /**
+     * 특정 행 업데이트.
+     *
+     * @param rowIndex 시트 행 번호 (1-based, findRow가 반환한 값 그대로 사용)
+     * @param values   교체할 셀 값 배열
+     * @param startCol 시작 열 문자 (기본값: 'A')
+     */
+    updateRow(rowIndex: number, values: string[], startCol?: string): Promise<void>;
+}
+declare function createSheetsClient(config: SheetsClientConfig): SheetsClient;
+
+/**
+ * 전화번호처럼 숫자만 남겨야 하는 값을 시트에 텍스트로 강제 저장.
+ * (앞에 ' 붙이면 구글 시트가 숫자 변환을 건너뜀)
+ */
+declare function toTextCell(value: string): string;
+/** 숫자만 추출 (전화번호 비교용) */
+declare function digitsOnly(value: string): string;
+/** 환경변수 래핑 따옴표 제거 */
+declare function stripQuotes(value: string): string;
+
+export { type FindResult, type RowMatcher, type ServiceAccountKey, SheetsClient, type SheetsClientConfig, createSheetsClient, digitsOnly, stripQuotes, toTextCell };

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+interface ServiceAccountKey {
+    client_email: string;
+    private_key: string;
+}
+interface SheetsClientConfig {
+    /** 서비스 계정 JSON (문자열 또는 객체) */
+    serviceAccountKey: string | ServiceAccountKey;
+    spreadsheetId: string;
+    sheetName: string;
+}
+interface FindResult {
+    /** 시트의 실제 행 번호 (1-based, 헤더 포함) — updateRow에 그대로 사용 가능 */
+    rowIndex: number;
+    values: string[];
+}
+type RowMatcher = Record<number, string> | ((row: string[], rowIndex: number) => boolean);
+
+declare class SheetsClient {
+    private readonly spreadsheetId;
+    private readonly sheetName;
+    private readonly serviceAccountKey;
+    constructor(config: SheetsClientConfig);
+    private sheets;
+    private range;
+    /** 시트 끝에 행 추가 */
+    appendRow(values: string[], range?: string): Promise<void>;
+    /** 지정 범위의 모든 행 반환 (각 셀은 trim된 문자열) */
+    getRows(range?: string): Promise<string[][]>;
+    /**
+     * 조건에 맞는 첫 번째 행을 반환.
+     *
+     * matcher가 Record이면 { [컬럼인덱스]: 기대값 } — 양쪽 trim+소문자 비교
+     * matcher가 함수이면 (row, rowIndex) => boolean — 커스텀 비교 가능
+     *
+     * @param skipHeader true이면 첫 번째 행(헤더)을 건너뜀 (기본값: true)
+     */
+    findRow(matcher: RowMatcher, options?: {
+        range?: string;
+        skipHeader?: boolean;
+    }): Promise<FindResult | null>;
+    /**
+     * 특정 행 업데이트.
+     *
+     * @param rowIndex 시트 행 번호 (1-based, findRow가 반환한 값 그대로 사용)
+     * @param values   교체할 셀 값 배열
+     * @param startCol 시작 열 문자 (기본값: 'A')
+     */
+    updateRow(rowIndex: number, values: string[], startCol?: string): Promise<void>;
+}
+declare function createSheetsClient(config: SheetsClientConfig): SheetsClient;
+
+/**
+ * 전화번호처럼 숫자만 남겨야 하는 값을 시트에 텍스트로 강제 저장.
+ * (앞에 ' 붙이면 구글 시트가 숫자 변환을 건너뜀)
+ */
+declare function toTextCell(value: string): string;
+/** 숫자만 추출 (전화번호 비교용) */
+declare function digitsOnly(value: string): string;
+/** 환경변수 래핑 따옴표 제거 */
+declare function stripQuotes(value: string): string;
+
+export { type FindResult, type RowMatcher, type ServiceAccountKey, SheetsClient, type SheetsClientConfig, createSheetsClient, digitsOnly, stripQuotes, toTextCell };

package/dist/index.js

@@ -0,0 +1,167 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SheetsClient: () => SheetsClient,
+  createSheetsClient: () => createSheetsClient,
+  digitsOnly: () => digitsOnly,
+  stripQuotes: () => stripQuotes,
+  toTextCell: () => toTextCell
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_googleapis = require("googleapis");
+
+// src/utils.ts
+function toTextCell(value) {
+  const digits = value.replace(/\D/g, "");
+  if (!digits) return "";
+  return `'${digits}`;
+}
+function digitsOnly(value) {
+  return value.replace(/\D/g, "");
+}
+function stripQuotes(value) {
+  const t = value.trim();
+  if (t.startsWith('"') && t.endsWith('"') || t.startsWith("'") && t.endsWith("'"))
+    return t.slice(1, -1);
+  return t;
+}
+
+// src/client.ts
+var SCOPE = "https://www.googleapis.com/auth/spreadsheets";
+function parseKey(key) {
+  if (typeof key !== "string") return key;
+  try {
+    const parsed = JSON.parse(key);
+    if (!parsed.client_email || !parsed.private_key) throw new Error();
+    return parsed;
+  } catch {
+    throw new Error("serviceAccountKey JSON \uD615\uC2DD\uC774 \uC720\uD6A8\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.");
+  }
+}
+function colLetter(index) {
+  let col = "";
+  let n = index + 1;
+  while (n > 0) {
+    col = String.fromCharCode((n - 1) % 26 + 65) + col;
+    n = Math.floor((n - 1) / 26);
+  }
+  return col;
+}
+var SheetsClient = class {
+  constructor(config) {
+    this.spreadsheetId = config.spreadsheetId;
+    this.sheetName = stripQuotes(config.sheetName);
+    this.serviceAccountKey = config.serviceAccountKey;
+  }
+  async sheets() {
+    const sa = parseKey(this.serviceAccountKey);
+    const auth = new import_googleapis.google.auth.JWT({
+      email: sa.client_email,
+      key: sa.private_key,
+      scopes: [SCOPE]
+    });
+    return import_googleapis.google.sheets({ version: "v4", auth });
+  }
+  range(r) {
+    return `${this.sheetName}!${r}`;
+  }
+  /** 시트 끝에 행 추가 */
+  async appendRow(values, range = "A:Z") {
+    const api = await this.sheets();
+    await api.spreadsheets.values.append({
+      spreadsheetId: this.spreadsheetId,
+      range: this.range(range),
+      valueInputOption: "USER_ENTERED",
+      requestBody: { values: [values] }
+    });
+  }
+  /** 지정 범위의 모든 행 반환 (각 셀은 trim된 문자열) */
+  async getRows(range = "A:Z") {
+    const api = await this.sheets();
+    const res = await api.spreadsheets.values.get({
+      spreadsheetId: this.spreadsheetId,
+      range: this.range(range)
+    });
+    return (res.data.values ?? []).map(
+      (row) => row.map((cell) => String(cell ?? "").trim())
+    );
+  }
+  /**
+   * 조건에 맞는 첫 번째 행을 반환.
+   *
+   * matcher가 Record이면 { [컬럼인덱스]: 기대값 } — 양쪽 trim+소문자 비교
+   * matcher가 함수이면 (row, rowIndex) => boolean — 커스텀 비교 가능
+   *
+   * @param skipHeader true이면 첫 번째 행(헤더)을 건너뜀 (기본값: true)
+   */
+  async findRow(matcher, options = {}) {
+    const { range = "A:Z", skipHeader = true } = options;
+    const rows = await this.getRows(range);
+    const start = skipHeader ? 1 : 0;
+    const matchFn = typeof matcher === "function" ? matcher : (row) => Object.entries(matcher).every(([col, expected]) => {
+      const cell = String(row[Number(col)] ?? "").trim().toLowerCase();
+      return cell === expected.trim().toLowerCase();
+    });
+    for (let i = start; i < rows.length; i++) {
+      const row = rows[i];
+      if (!row) continue;
+      if (matchFn(row, i + 1)) {
+        return { rowIndex: i + 1, values: row };
+      }
+    }
+    return null;
+  }
+  /**
+   * 특정 행 업데이트.
+   *
+   * @param rowIndex 시트 행 번호 (1-based, findRow가 반환한 값 그대로 사용)
+   * @param values   교체할 셀 값 배열
+   * @param startCol 시작 열 문자 (기본값: 'A')
+   */
+  async updateRow(rowIndex, values, startCol = "A") {
+    if (!Number.isInteger(rowIndex) || rowIndex < 2) {
+      throw new Error("rowIndex\uB294 2 \uC774\uC0C1\uC758 \uC815\uC218\uC5EC\uC57C \uD569\uB2C8\uB2E4.");
+    }
+    const api = await this.sheets();
+    const startColIndex = startCol.toUpperCase().charCodeAt(0) - 65;
+    const endCol = colLetter(startColIndex + values.length - 1);
+    await api.spreadsheets.values.update({
+      spreadsheetId: this.spreadsheetId,
+      range: this.range(`${startCol}${rowIndex}:${endCol}${rowIndex}`),
+      valueInputOption: "USER_ENTERED",
+      requestBody: { values: [values] }
+    });
+  }
+};
+function createSheetsClient(config) {
+  return new SheetsClient(config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SheetsClient,
+  createSheetsClient,
+  digitsOnly,
+  stripQuotes,
+  toTextCell
+});

package/dist/index.mjs

@@ -0,0 +1,136 @@
+// src/client.ts
+import { google } from "googleapis";
+
+// src/utils.ts
+function toTextCell(value) {
+  const digits = value.replace(/\D/g, "");
+  if (!digits) return "";
+  return `'${digits}`;
+}
+function digitsOnly(value) {
+  return value.replace(/\D/g, "");
+}
+function stripQuotes(value) {
+  const t = value.trim();
+  if (t.startsWith('"') && t.endsWith('"') || t.startsWith("'") && t.endsWith("'"))
+    return t.slice(1, -1);
+  return t;
+}
+
+// src/client.ts
+var SCOPE = "https://www.googleapis.com/auth/spreadsheets";
+function parseKey(key) {
+  if (typeof key !== "string") return key;
+  try {
+    const parsed = JSON.parse(key);
+    if (!parsed.client_email || !parsed.private_key) throw new Error();
+    return parsed;
+  } catch {
+    throw new Error("serviceAccountKey JSON \uD615\uC2DD\uC774 \uC720\uD6A8\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.");
+  }
+}
+function colLetter(index) {
+  let col = "";
+  let n = index + 1;
+  while (n > 0) {
+    col = String.fromCharCode((n - 1) % 26 + 65) + col;
+    n = Math.floor((n - 1) / 26);
+  }
+  return col;
+}
+var SheetsClient = class {
+  constructor(config) {
+    this.spreadsheetId = config.spreadsheetId;
+    this.sheetName = stripQuotes(config.sheetName);
+    this.serviceAccountKey = config.serviceAccountKey;
+  }
+  async sheets() {
+    const sa = parseKey(this.serviceAccountKey);
+    const auth = new google.auth.JWT({
+      email: sa.client_email,
+      key: sa.private_key,
+      scopes: [SCOPE]
+    });
+    return google.sheets({ version: "v4", auth });
+  }
+  range(r) {
+    return `${this.sheetName}!${r}`;
+  }
+  /** 시트 끝에 행 추가 */
+  async appendRow(values, range = "A:Z") {
+    const api = await this.sheets();
+    await api.spreadsheets.values.append({
+      spreadsheetId: this.spreadsheetId,
+      range: this.range(range),
+      valueInputOption: "USER_ENTERED",
+      requestBody: { values: [values] }
+    });
+  }
+  /** 지정 범위의 모든 행 반환 (각 셀은 trim된 문자열) */
+  async getRows(range = "A:Z") {
+    const api = await this.sheets();
+    const res = await api.spreadsheets.values.get({
+      spreadsheetId: this.spreadsheetId,
+      range: this.range(range)
+    });
+    return (res.data.values ?? []).map(
+      (row) => row.map((cell) => String(cell ?? "").trim())
+    );
+  }
+  /**
+   * 조건에 맞는 첫 번째 행을 반환.
+   *
+   * matcher가 Record이면 { [컬럼인덱스]: 기대값 } — 양쪽 trim+소문자 비교
+   * matcher가 함수이면 (row, rowIndex) => boolean — 커스텀 비교 가능
+   *
+   * @param skipHeader true이면 첫 번째 행(헤더)을 건너뜀 (기본값: true)
+   */
+  async findRow(matcher, options = {}) {
+    const { range = "A:Z", skipHeader = true } = options;
+    const rows = await this.getRows(range);
+    const start = skipHeader ? 1 : 0;
+    const matchFn = typeof matcher === "function" ? matcher : (row) => Object.entries(matcher).every(([col, expected]) => {
+      const cell = String(row[Number(col)] ?? "").trim().toLowerCase();
+      return cell === expected.trim().toLowerCase();
+    });
+    for (let i = start; i < rows.length; i++) {
+      const row = rows[i];
+      if (!row) continue;
+      if (matchFn(row, i + 1)) {
+        return { rowIndex: i + 1, values: row };
+      }
+    }
+    return null;
+  }
+  /**
+   * 특정 행 업데이트.
+   *
+   * @param rowIndex 시트 행 번호 (1-based, findRow가 반환한 값 그대로 사용)
+   * @param values   교체할 셀 값 배열
+   * @param startCol 시작 열 문자 (기본값: 'A')
+   */
+  async updateRow(rowIndex, values, startCol = "A") {
+    if (!Number.isInteger(rowIndex) || rowIndex < 2) {
+      throw new Error("rowIndex\uB294 2 \uC774\uC0C1\uC758 \uC815\uC218\uC5EC\uC57C \uD569\uB2C8\uB2E4.");
+    }
+    const api = await this.sheets();
+    const startColIndex = startCol.toUpperCase().charCodeAt(0) - 65;
+    const endCol = colLetter(startColIndex + values.length - 1);
+    await api.spreadsheets.values.update({
+      spreadsheetId: this.spreadsheetId,
+      range: this.range(`${startCol}${rowIndex}:${endCol}${rowIndex}`),
+      valueInputOption: "USER_ENTERED",
+      requestBody: { values: [values] }
+    });
+  }
+};
+function createSheetsClient(config) {
+  return new SheetsClient(config);
+}
+export {
+  SheetsClient,
+  createSheetsClient,
+  digitsOnly,
+  stripQuotes,
+  toTextCell
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@moonhr/sheets-client",
+  "version": "0.1.0",
+  "description": "Google Sheets client for form-based data collection",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "dependencies": {
+    "googleapis": "^148.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": ["google-sheets", "spreadsheet", "form"],
+  "license": "MIT"
+}