connectbase-client 0.12.2 → 0.13.0

package/dist/index.js

@@ -37,10 +37,12 @@ module.exports = __toCommonJS(index_exports);
 
 // src/types/error.ts
 var ApiError = class extends Error {
-  constructor(statusCode, message) {
+  constructor(statusCode, message, code, details) {
     super(message);
     this.statusCode = statusCode;
     this.name = "ApiError";
+    this.code = code;
+    this.details = details;
   }
 };
 var AuthError = class extends Error {
@@ -193,7 +195,17 @@ var HttpClient = class {
       const errorData = await response.json().catch(() => ({
         message: response.statusText
       }));
-      throw new ApiError(response.status, errorData.message || errorData.error || "Unknown error");
+      const rawError = errorData.error;
+      if (rawError && typeof rawError === "object" && "message" in rawError) {
+        throw new ApiError(
+          response.status,
+          rawError.message || "Unknown error",
+          rawError.code,
+          rawError.details
+        );
+      }
+      const message = typeof rawError === "string" ? rawError : errorData.message || "Unknown error";
+      throw new ApiError(response.status, message);
     }
     if (response.status === 204 || response.headers.get("content-length") === "0") {
       return {};
@@ -550,10 +562,15 @@ var DatabaseAPI = class {
     this.http = http;
   }
   /**
-   * API Key 인증 시 /v1/public 접두사 반환
+   * Database 공개 API 접두사.
+   *
+   * 서버의 테이블/컬럼/데이터 CRUD 는 모두 `/v1/public/*` 경로에서만 제공되며
+   * (core-server → data-server 프록시), JWT 기반 `/v1/*` 경로는 존재하지 않습니다.
+   * 따라서 항상 `/v1/public` 을 사용합니다. 인증은 `X-Public-Key` 헤더에
+   * `publicKey` (`cb_pk_*`) 를 실어 서버가 검증합니다.
    */
   getPublicPrefix() {
-    return this.http.hasPublicKey() ? "/v1/public" : "/v1";
+    return "/v1/public";
   }
   // ============ Table Methods ============
   /**
@@ -574,18 +591,39 @@ var DatabaseAPI = class {
     return this.http.get(`${prefix}/tables/${tableId}`);
   }
   /**
-   * 테이블 생성
+   * 테이블 생성.
+   *
+   * 서버 DTO (`{title, schema, access_level}`) 로 변환하여 전송합니다.
+   * `schema` 가 비어있으면 요청 본문에서 키 자체를 생략하여 빈 테이블을
+   * 생성합니다. (서버는 explicit 빈 맵을 거부)
+   *
+   * 서버는 `{message}` 만 돌려주므로 반환 타입은 `void` 입니다.
+   * 생성된 테이블 메타데이터가 필요하면 이어서 `getTables()` 로 조회하세요.
    */
   async createTable(data) {
     const prefix = this.getPublicPrefix();
-    return this.http.post(`${prefix}/tables`, data);
+    const body = {
+      title: data.name,
+      access_level: data.accessLevel ?? "Creator"
+    };
+    if (data.schema && Object.keys(data.schema).length > 0) {
+      body.schema = data.schema;
+    }
+    await this.http.post(`${prefix}/tables`, body);
   }
   /**
-   * 테이블 수정
+   * 테이블 수정.
+   *
+   * `name` 은 서버의 `title` 로, `accessLevel` 은 `access_level` 로 매핑됩니다.
    */
   async updateTable(tableId, data) {
     const prefix = this.getPublicPrefix();
-    await this.http.patch(`${prefix}/tables/${tableId}`, data);
+    const body = {};
+    if (data.name !== void 0) body.title = data.name;
+    if (data.schema !== void 0) body.schema = data.schema;
+    if (data.accessLevel !== void 0) body.access_level = data.accessLevel;
+    if (data.description !== void 0) body.description = data.description;
+    await this.http.patch(`${prefix}/tables/${tableId}`, body);
   }
   /**
    * 테이블 삭제
@@ -594,48 +632,139 @@ var DatabaseAPI = class {
     const prefix = this.getPublicPrefix();
     await this.http.delete(`${prefix}/tables/${tableId}`);
   }
+  // ============ Validation Schema Methods (table-level 검증 규칙) ============
+  /**
+   * 테이블 검증 스키마 조회.
+   *
+   * 검증 스키마가 설정되어 있지 않으면 `null` 을 반환합니다.
+   * Public Key 인증으로 호출 가능 (조회 권한).
+   */
+  async getValidationSchema(tableId) {
+    const prefix = this.getPublicPrefix();
+    const response = await this.http.get(
+      `${prefix}/tables/${tableId}/validation-schema`
+    );
+    return response.validation_schema;
+  }
+  /**
+   * 테이블 검증 스키마 설정/교체.
+   *
+   * **권한**: 콘솔 (앱 소유자 JWT) 전용. Public Key 로는 설정 불가.
+   * SDK 에서는 `accessToken` 이 설정되어 있어야 하며, 콘솔에서 사용하는 패턴입니다.
+   *
+   * 빈 fields 는 거부됩니다. 검증 스키마를 제거하려면 `deleteValidationSchema` 사용.
+   *
+   * @example
+   * ```ts
+   * await cb.database.setValidationSchema(tableId, {
+   *     fields: {
+   *         email: { type: 'string', pattern: '^.+@.+$', required: true },
+   *         age: { type: 'int', min: 0, max: 150 }
+   *     },
+   *     required: ['email'],
+   *     immutable: ['email']
+   * })
+   * ```
+   */
+  async setValidationSchema(tableId, schema) {
+    await this.http.put(
+      `/v1/apps/${this.requireAppId()}/databases/tables/${tableId}/validation-schema`,
+      { validation_schema: schema }
+    );
+  }
+  /**
+   * 테이블 검증 스키마 제거 (schemaless 모드로 복귀).
+   *
+   * **권한**: 콘솔 (앱 소유자 JWT) 전용.
+   */
+  async deleteValidationSchema(tableId) {
+    await this.http.delete(
+      `/v1/apps/${this.requireAppId()}/databases/tables/${tableId}/validation-schema`
+    );
+  }
+  /**
+   * appId 가 설정되어 있어야 콘솔 경로를 호출할 수 있습니다 (validation_schema set/delete).
+   */
+  requireAppId() {
+    const appId = this.http.config?.appId;
+    if (!appId) {
+      throw new Error(
+        "setValidationSchema/deleteValidationSchema \uB294 \uCF58\uC194 (JWT) \uC778\uC99D\uC774 \uD544\uC694\uD558\uBA70 ConnectBase config \uC5D0 appId \uAC00 \uC124\uC815\uB418\uC5B4\uC57C \uD569\uB2C8\uB2E4."
+      );
+    }
+    return appId;
+  }
   // ============ Column Methods ============
   /**
-   * 컬럼 목록 조회 (Table.schema에서 추출)
+   * 컬럼 목록 조회 (`Table.schema` 맵을 컬럼 객체 배열로 변환).
+   *
+   * 서버는 컬럼을 다음 두 가지 중 하나로 저장합니다:
+   * - 플랫: `"email": "string"` (추가 속성이 없는 경우)
+   * - 중첩: `"email": { "type": "string", "required": true, ... }` (추가 속성이 있는 경우)
+   *
+   * `$required` 키는 별도 배열로 필수 컬럼을 지정할 수 있으며, 중첩 객체의
+   * `required: true` 와 병합되어 판정됩니다.
    */
   async getColumns(tableId) {
     const table = await this.getTable(tableId);
-    const schema = table.schema;
-    if (!schema) return [];
+    const schema = table.schema ?? {};
+    const requiredSet = new Set(
+      Array.isArray(schema.$required) ? schema.$required : []
+    );
     const columns = [];
+    let order = 0;
     for (const [name, def] of Object.entries(schema)) {
-      if (name.startsWith("$")) continue;
-      const colDef = def;
+      if (name.startsWith("$") || def === void 0) continue;
+      if (Array.isArray(def)) continue;
+      let data_type = "string";
+      let is_required = requiredSet.has(name);
+      let default_value;
+      let description;
+      let encrypted;
+      if (typeof def === "string") {
+        data_type = def;
+      } else {
+        data_type = def.type;
+        if (def.required === true) is_required = true;
+        if (def.default !== void 0) default_value = def.default;
+        if (def.description !== void 0) description = def.description;
+        if (def.encrypted !== void 0) encrypted = def.encrypted;
+      }
       columns.push({
         id: name,
         name,
-        data_type: colDef.type || "string",
-        is_required: colDef.required || false,
-        default_value: colDef.default,
-        description: colDef.description,
-        encrypted: colDef.encrypted,
-        order: 0,
-        created_at: ""
+        data_type,
+        is_required,
+        default_value,
+        description,
+        encrypted,
+        order: order++,
+        created_at: table.created_at
       });
     }
     return columns;
   }
   /**
-   * 컬럼 생성
+   * 컬럼 생성.
+   *
+   * 서버는 `{message}` 만 돌려주므로 반환 타입은 `void` 입니다.
+   * 생성 결과 컬럼을 얻으려면 이어서 `getColumns(tableId)` 로 조회하세요.
    */
   async createColumn(tableId, data) {
     const prefix = this.getPublicPrefix();
-    return this.http.post(
+    await this.http.post(
       `${prefix}/tables/${tableId}/columns`,
       data
     );
   }
   /**
-   * 컬럼 수정
+   * 컬럼 수정.
+   *
+   * 서버는 `{message}` 만 돌려주므로 반환 타입은 `void` 입니다.
    */
   async updateColumn(tableId, columnName, data) {
     const prefix = this.getPublicPrefix();
-    return this.http.patch(
+    await this.http.patch(
       `${prefix}/tables/${tableId}/columns/${columnName}`,
       data
     );
@@ -689,11 +818,27 @@ var DatabaseAPI = class {
     return this.http.get(`${prefix}/tables/${tableId}/data/${dataId}`);
   }
   /**
-   * 데이터 생성
+   * 데이터 생성.
+   *
+   * `tableIdOrName` 은 테이블 UUID 또는 이름. UUID 형식이면 기존 경로
+   * (`/tables/:tableId/data`), 그렇지 않으면 이름 기반 경로
+   * (`/tables/name/:tableName/data`) 를 사용합니다.
+   *
+   * `options.autoCreate: true` 시 테이블이 없으면 빈 schemaless 테이블을
+   * 자동으로 생성한 뒤 insert. opt-in 이며 프로토타입/AI 자동화 워크플로에
+   * 권장합니다. production 앱은 명시적 `createTable` 호출 권장.
    */
-  async createData(tableId, data) {
+  async createData(tableIdOrName, data, options) {
     const prefix = this.getPublicPrefix();
-    return this.http.post(`${prefix}/tables/${tableId}/data`, data);
+    const isUUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(tableIdOrName);
+    if (isUUID) {
+      return this.http.post(`${prefix}/tables/${tableIdOrName}/data`, data);
+    }
+    const query = options?.autoCreate ? "?auto_create=true" : "";
+    return this.http.post(
+      `${prefix}/tables/name/${encodeURIComponent(tableIdOrName)}/data${query}`,
+      data
+    );
   }
   /**
    * 데이터 수정 (부분 업데이트)

package/dist/index.mjs

@@ -1,9 +1,11 @@
 // src/types/error.ts
 var ApiError = class extends Error {
-  constructor(statusCode, message) {
+  constructor(statusCode, message, code, details) {
     super(message);
     this.statusCode = statusCode;
     this.name = "ApiError";
+    this.code = code;
+    this.details = details;
   }
 };
 var AuthError = class extends Error {
@@ -156,7 +158,17 @@ var HttpClient = class {
       const errorData = await response.json().catch(() => ({
         message: response.statusText
       }));
-      throw new ApiError(response.status, errorData.message || errorData.error || "Unknown error");
+      const rawError = errorData.error;
+      if (rawError && typeof rawError === "object" && "message" in rawError) {
+        throw new ApiError(
+          response.status,
+          rawError.message || "Unknown error",
+          rawError.code,
+          rawError.details
+        );
+      }
+      const message = typeof rawError === "string" ? rawError : errorData.message || "Unknown error";
+      throw new ApiError(response.status, message);
     }
     if (response.status === 204 || response.headers.get("content-length") === "0") {
       return {};
@@ -513,10 +525,15 @@ var DatabaseAPI = class {
     this.http = http;
   }
   /**
-   * API Key 인증 시 /v1/public 접두사 반환
+   * Database 공개 API 접두사.
+   *
+   * 서버의 테이블/컬럼/데이터 CRUD 는 모두 `/v1/public/*` 경로에서만 제공되며
+   * (core-server → data-server 프록시), JWT 기반 `/v1/*` 경로는 존재하지 않습니다.
+   * 따라서 항상 `/v1/public` 을 사용합니다. 인증은 `X-Public-Key` 헤더에
+   * `publicKey` (`cb_pk_*`) 를 실어 서버가 검증합니다.
    */
   getPublicPrefix() {
-    return this.http.hasPublicKey() ? "/v1/public" : "/v1";
+    return "/v1/public";
   }
   // ============ Table Methods ============
   /**
@@ -537,18 +554,39 @@ var DatabaseAPI = class {
     return this.http.get(`${prefix}/tables/${tableId}`);
   }
   /**
-   * 테이블 생성
+   * 테이블 생성.
+   *
+   * 서버 DTO (`{title, schema, access_level}`) 로 변환하여 전송합니다.
+   * `schema` 가 비어있으면 요청 본문에서 키 자체를 생략하여 빈 테이블을
+   * 생성합니다. (서버는 explicit 빈 맵을 거부)
+   *
+   * 서버는 `{message}` 만 돌려주므로 반환 타입은 `void` 입니다.
+   * 생성된 테이블 메타데이터가 필요하면 이어서 `getTables()` 로 조회하세요.
    */
   async createTable(data) {
     const prefix = this.getPublicPrefix();
-    return this.http.post(`${prefix}/tables`, data);
+    const body = {
+      title: data.name,
+      access_level: data.accessLevel ?? "Creator"
+    };
+    if (data.schema && Object.keys(data.schema).length > 0) {
+      body.schema = data.schema;
+    }
+    await this.http.post(`${prefix}/tables`, body);
   }
   /**
-   * 테이블 수정
+   * 테이블 수정.
+   *
+   * `name` 은 서버의 `title` 로, `accessLevel` 은 `access_level` 로 매핑됩니다.
    */
   async updateTable(tableId, data) {
     const prefix = this.getPublicPrefix();
-    await this.http.patch(`${prefix}/tables/${tableId}`, data);
+    const body = {};
+    if (data.name !== void 0) body.title = data.name;
+    if (data.schema !== void 0) body.schema = data.schema;
+    if (data.accessLevel !== void 0) body.access_level = data.accessLevel;
+    if (data.description !== void 0) body.description = data.description;
+    await this.http.patch(`${prefix}/tables/${tableId}`, body);
   }
   /**
    * 테이블 삭제
@@ -557,48 +595,139 @@ var DatabaseAPI = class {
     const prefix = this.getPublicPrefix();
     await this.http.delete(`${prefix}/tables/${tableId}`);
   }
+  // ============ Validation Schema Methods (table-level 검증 규칙) ============
+  /**
+   * 테이블 검증 스키마 조회.
+   *
+   * 검증 스키마가 설정되어 있지 않으면 `null` 을 반환합니다.
+   * Public Key 인증으로 호출 가능 (조회 권한).
+   */
+  async getValidationSchema(tableId) {
+    const prefix = this.getPublicPrefix();
+    const response = await this.http.get(
+      `${prefix}/tables/${tableId}/validation-schema`
+    );
+    return response.validation_schema;
+  }
+  /**
+   * 테이블 검증 스키마 설정/교체.
+   *
+   * **권한**: 콘솔 (앱 소유자 JWT) 전용. Public Key 로는 설정 불가.
+   * SDK 에서는 `accessToken` 이 설정되어 있어야 하며, 콘솔에서 사용하는 패턴입니다.
+   *
+   * 빈 fields 는 거부됩니다. 검증 스키마를 제거하려면 `deleteValidationSchema` 사용.
+   *
+   * @example
+   * ```ts
+   * await cb.database.setValidationSchema(tableId, {
+   *     fields: {
+   *         email: { type: 'string', pattern: '^.+@.+$', required: true },
+   *         age: { type: 'int', min: 0, max: 150 }
+   *     },
+   *     required: ['email'],
+   *     immutable: ['email']
+   * })
+   * ```
+   */
+  async setValidationSchema(tableId, schema) {
+    await this.http.put(
+      `/v1/apps/${this.requireAppId()}/databases/tables/${tableId}/validation-schema`,
+      { validation_schema: schema }
+    );
+  }
+  /**
+   * 테이블 검증 스키마 제거 (schemaless 모드로 복귀).
+   *
+   * **권한**: 콘솔 (앱 소유자 JWT) 전용.
+   */
+  async deleteValidationSchema(tableId) {
+    await this.http.delete(
+      `/v1/apps/${this.requireAppId()}/databases/tables/${tableId}/validation-schema`
+    );
+  }
+  /**
+   * appId 가 설정되어 있어야 콘솔 경로를 호출할 수 있습니다 (validation_schema set/delete).
+   */
+  requireAppId() {
+    const appId = this.http.config?.appId;
+    if (!appId) {
+      throw new Error(
+        "setValidationSchema/deleteValidationSchema \uB294 \uCF58\uC194 (JWT) \uC778\uC99D\uC774 \uD544\uC694\uD558\uBA70 ConnectBase config \uC5D0 appId \uAC00 \uC124\uC815\uB418\uC5B4\uC57C \uD569\uB2C8\uB2E4."
+      );
+    }
+    return appId;
+  }
   // ============ Column Methods ============
   /**
-   * 컬럼 목록 조회 (Table.schema에서 추출)
+   * 컬럼 목록 조회 (`Table.schema` 맵을 컬럼 객체 배열로 변환).
+   *
+   * 서버는 컬럼을 다음 두 가지 중 하나로 저장합니다:
+   * - 플랫: `"email": "string"` (추가 속성이 없는 경우)
+   * - 중첩: `"email": { "type": "string", "required": true, ... }` (추가 속성이 있는 경우)
+   *
+   * `$required` 키는 별도 배열로 필수 컬럼을 지정할 수 있으며, 중첩 객체의
+   * `required: true` 와 병합되어 판정됩니다.
    */
   async getColumns(tableId) {
     const table = await this.getTable(tableId);
-    const schema = table.schema;
-    if (!schema) return [];
+    const schema = table.schema ?? {};
+    const requiredSet = new Set(
+      Array.isArray(schema.$required) ? schema.$required : []
+    );
     const columns = [];
+    let order = 0;
     for (const [name, def] of Object.entries(schema)) {
-      if (name.startsWith("$")) continue;
-      const colDef = def;
+      if (name.startsWith("$") || def === void 0) continue;
+      if (Array.isArray(def)) continue;
+      let data_type = "string";
+      let is_required = requiredSet.has(name);
+      let default_value;
+      let description;
+      let encrypted;
+      if (typeof def === "string") {
+        data_type = def;
+      } else {
+        data_type = def.type;
+        if (def.required === true) is_required = true;
+        if (def.default !== void 0) default_value = def.default;
+        if (def.description !== void 0) description = def.description;
+        if (def.encrypted !== void 0) encrypted = def.encrypted;
+      }
       columns.push({
         id: name,
         name,
-        data_type: colDef.type || "string",
-        is_required: colDef.required || false,
-        default_value: colDef.default,
-        description: colDef.description,
-        encrypted: colDef.encrypted,
-        order: 0,
-        created_at: ""
+        data_type,
+        is_required,
+        default_value,
+        description,
+        encrypted,
+        order: order++,
+        created_at: table.created_at
       });
     }
     return columns;
   }
   /**
-   * 컬럼 생성
+   * 컬럼 생성.
+   *
+   * 서버는 `{message}` 만 돌려주므로 반환 타입은 `void` 입니다.
+   * 생성 결과 컬럼을 얻으려면 이어서 `getColumns(tableId)` 로 조회하세요.
    */
   async createColumn(tableId, data) {
     const prefix = this.getPublicPrefix();
-    return this.http.post(
+    await this.http.post(
       `${prefix}/tables/${tableId}/columns`,
       data
     );
   }
   /**
-   * 컬럼 수정
+   * 컬럼 수정.
+   *
+   * 서버는 `{message}` 만 돌려주므로 반환 타입은 `void` 입니다.
    */
   async updateColumn(tableId, columnName, data) {
     const prefix = this.getPublicPrefix();
-    return this.http.patch(
+    await this.http.patch(
       `${prefix}/tables/${tableId}/columns/${columnName}`,
       data
     );
@@ -652,11 +781,27 @@ var DatabaseAPI = class {
     return this.http.get(`${prefix}/tables/${tableId}/data/${dataId}`);
   }
   /**
-   * 데이터 생성
+   * 데이터 생성.
+   *
+   * `tableIdOrName` 은 테이블 UUID 또는 이름. UUID 형식이면 기존 경로
+   * (`/tables/:tableId/data`), 그렇지 않으면 이름 기반 경로
+   * (`/tables/name/:tableName/data`) 를 사용합니다.
+   *
+   * `options.autoCreate: true` 시 테이블이 없으면 빈 schemaless 테이블을
+   * 자동으로 생성한 뒤 insert. opt-in 이며 프로토타입/AI 자동화 워크플로에
+   * 권장합니다. production 앱은 명시적 `createTable` 호출 권장.
    */
-  async createData(tableId, data) {
+  async createData(tableIdOrName, data, options) {
     const prefix = this.getPublicPrefix();
-    return this.http.post(`${prefix}/tables/${tableId}/data`, data);
+    const isUUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(tableIdOrName);
+    if (isUUID) {
+      return this.http.post(`${prefix}/tables/${tableIdOrName}/data`, data);
+    }
+    const query = options?.autoCreate ? "?auto_create=true" : "";
+    return this.http.post(
+      `${prefix}/tables/name/${encodeURIComponent(tableIdOrName)}/data${query}`,
+      data
+    );
   }
   /**
    * 데이터 수정 (부분 업데이트)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "connectbase-client",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "Connect Base JavaScript/TypeScript SDK for browser and Node.js",
   "repository": {
     "type": "git",
@@ -33,6 +33,7 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
+    "test:types": "tsc --noEmit -p test/tsconfig.json",
     "release": "pnpm build && npm publish --access public"
   },
   "keywords": [