Status SDK

설치

npm i @the-seeker/status-sdk

이벤트 전송

createStatusClient는 ingest endpoint와 프로젝트 키를 사용합니다. secret은 환경 변수로만 전달하세요.

import { createStatusClient } from "@the-seeker/status-sdk";

const status = createStatusClient({
  keyId: process.env.STATUS_KEY_ID!,
  secret: process.env.STATUS_SECRET!,
  endpoint: "https://ingest.example.com/v1/events",
  slug: "checkout-api",
});

await status.report({ result: "ok", latencyMs: 123 });

이벤트마다 slug를 덮어쓸 수도 있습니다. 기본 slug와 이벤트 slug가 모두 없으면 SDK가 오류를 발생시킵니다.

피드백 전송

await status.sendFeedback({
  uid: "user-123",
  content: "검색 결과가 느립니다.",
  fields: { plan: "pro" },
});

상태 페이지 관리

createStatusAdminClient는 CRM 앱 origin과 관리 API 키를 사용합니다. ingest 클라이언트와 자격증명이 다릅니다.

const admin = createStatusAdminClient({
  baseUrl: "https://crm.theseeker.io",
  keyId: process.env.STATUS_ADMIN_KEY_ID!,
  secret: process.env.STATUS_ADMIN_KEY_SECRET!,
});
const page = await admin.getStatusPage();

4xx는 StatusAdminApiError로 즉시 전달되고, 네트워크와 5xx 오류는 기본 재시도 정책을 따릅니다.

서버 오류 수집

@the-seeker/status-sdk 0.3.0부터 createErrorClient로 Node 프로세스의 오류를 수집할 수 있습니다. 프로젝트 키에는 errors:write가 필요합니다.

import { createErrorClient } from "@the-seeker/status-sdk";

const errors = createErrorClient({
  keyId: process.env.CRM_KEY_ID!,
  secret: process.env.CRM_KEY_SECRET!,
  domain: "example.com", // 또는 propertyId, 둘 중 하나만 지정
  release: "web-1.2.3",
  environment: "production",
});

errors.setUser({ id: "user-123" });
errors.setTag("component", "checkout");
errors.addBreadcrumb({ category: "log", message: "checkout started" });
const result = await errors.captureException(new Error("checkout failed"));
await errors.captureMessage("checkout warning", "warning");
await errors.flush();

captureException과 captureMessage는 { ok, status, issueId, error } 결과를 반환하며 기본적으로 전송 실패를 throw하지 않습니다. onError로 실패를 관찰할 수 있습니다. installGlobalHandlers()는 uncaught exception과 unhandled rejection을 fatal로 전송하고 flush한 뒤 오류를 출력하고 프로세스를 종료합니다. 각각 onUncaughtException: "continue", onUnhandledRejection: "continue"로 동작을 바꿀 수 있으며 반환된 함수를 호출해 핸들러를 해제합니다.

Breadcrumb 버퍼는 최근 50건입니다. 이메일 주소, Bearer 자격증명, 12자리 이상 연속 숫자는 전송 전에 가립니다. 폼 입력 값은 breadcrumb에 기록하지 마세요.

Python SDK theseeker-status도 create_error_client()와 ErrorClient를 제공합니다. install_excepthook()은 기존 sys.excepthook 및 threading hook을 호출해 애플리케이션의 기본 오류 처리를 유지합니다. 상세 예제와 Django/FastAPI 적용은 Python SDK README를 참고하세요.

Source Maps CLI

CLI는 theseeker-sourcemaps upload|list|delete를 제공합니다. THESEEKER_API_KEY=keyId.secret 또는 --api-key를 사용하고, 기본 endpoint는 https://crm.theseeker.io입니다. 업로드 기본 URL prefix는 ~/입니다.

npx theseeker-sourcemaps upload --release web-1.2.3 --domain example.com \
  --url-prefix https://example.com/_next/static/ .next/static
npx theseeker-sourcemaps list --domain example.com
npx theseeker-sourcemaps delete --release web-1.2.3 --domain example.com

--property-id는 --domain 대신 쓸 수 있습니다. --url-prefix는 끝에 /가 있는 HTTP(S) URL, /path/ 또는 ~/path/여야 합니다. CLI는 node_modules를 제외해 .map 파일을 재귀 탐색하고 최대 100개, 합계 25 MiB 단위로 업로드합니다. 파일당 한도는 15 MiB입니다. --dry-run은 업로드 경로 또는 실행할 API URL을 표시합니다. --endpoint로 CRM base URL을 바꿀 수 있습니다.

프로덕션 소스맵을 만들려면 Next.js 설정에 productionBrowserSourceMaps: true를 지정하세요. 업로드가 끝나면 공개 빌드 출력에서 .map 파일을 삭제하세요. 소스맵에 원본 코드가 들어갈 수 있습니다. 한 릴리스는 최대 1,000개 파일, 프로퍼티는 압축 저장 기준 1 GiB까지 보관합니다. 세부 endpoint와 오류 코드는 Source Maps API를 참고하세요.