AXHubAXHub
⌘K

SDK 호출

앱에서 로그인 사용자·앱 데이터·외부 DB를 쉽게 불러오는 @ax-hub/sdk 사용법이에요.

앱에서 AxHub 백엔드가 필요할 때 — 누가 로그인했는지, 앱 데이터, 외부 DB — @ax-hub/sdk로 불러와요. 주소·인증·에러를 일일이 챙기지 않아도 돼요.

템플릿으로 만든 앱엔 이미 들어 있어요. Next.js 템플릿이면 lib/axhub-server.ts의 makeAxhub()·makeApp()를 그대로 쓰면 됩니다.

시작하기

대부분은 이 두 줄이면 돼요. 인증은 템플릿이 로그인한 사용자로 알아서 연결해 줘요.

const sdk = await makeAxhub(); // 로그인한 사용자로 연결
const app = await makeApp();   // 이 앱에 연결

makeAxhub·makeApp는 서버에서만 써요 (서버 컴포넌트·라우트 핸들러·서버 액션). 화면(클라이언트) 코드에서는 쓰지 마세요.

앱 밖(에이전트·CI·외부 스크립트)에서 쓸 땐 개인 토큰(PAT)으로 직접 연결해요. 앱 안에서는 위 두 줄이면 충분해요.

로그인한 사용자

누가 들어왔는지 알 수 있어요.

const me = await sdk.identity.me();
// me.email, me.name, me.tenants (소속 회사와 역할)

앱 데이터 다루기

테이블을 불러와 읽고 써요.

const app = await makeApp();
const todos = await app.data.discover('todos'); // 테이블 구조를 알아서 파악
await todos.list({ limit: 20 });                 // 읽기
await todos.insert({ title: '할 일', done: false }); // 쓰기

빠르게 시작할 땐 discover('테이블이름')이면 충분해요. 조건을 걸어 찾고 싶으면 where로 짜요 (직접 SQL을 쓰지 않아도 돼요).

import { defineSchema, where, and } from '@ax-hub/sdk';

const Orders = defineSchema({ table: 'orders', columns: { status: 'string', total: 'number' } });

const paid = await app.data.table(Orders).list({
  where: and(where('status').eq('paid'), where('total').gt(100)),
});

외부 DB 불러오기

연결해 둔 외부 DB는 게이트웨이로 조회해요. connector 이름만 주면 돼요.

const res = await queryConnector({
  connector: 'my-db',
  path: 'public/employees',
  sql: 'SELECT id, name FROM employees WHERE active = ? LIMIT ?',
  params: [true, 10], // 값은 ? 로 따로 넘겨요 (SQL 문자열에 직접 박지 않기)
});
// res.rows 에 결과가, res.allowed 가 false 면 권한 거부예요

오류가 났을 때

SDK는 e.code로 무슨 오류인지 알려줘요. 메시지 글자를 비교하지 말고 code로 분기하세요 (메시지는 바뀔 수 있어요).

import { AxHubError, ConflictError } from '@ax-hub/sdk';

try {
  await todos.insert({ id: 't1' });
} catch (e) {
  if (e instanceof ConflictError) {
    // 이미 있는 값(중복) 처리
  } else if (e instanceof AxHubError) {
    console.error(e.code, e.requestId);
  }
}