설정
listingsapi-js 클라이언트의 API 키 결정 방식, 기본 URL 재정의, 타임아웃, 자동 재시도를 설정합니다.
생성자 옵션
ListingsAPI는 옵션 객체 1개를 받으며, 객체 자체와 모든 옵션은 생략할 수 있습니다:
import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI(); // reads LISTINGSAPI_KEY from env // Every default spelled out:const custom = new ListingsAPI({apiKey: process.env.LISTINGSAPI_KEY,baseUrl: 'https://listingsapi.com',timeout: 240000, // 4 minutes per attemptmaxRetries: 2, // up to 3 attempts total});API 키 결정 방식
키를 소스 코드에 하드코딩하지 마십시오. 인수 없이 호출한 생성자는 환경에서 LISTINGSAPI_KEY를 읽습니다:
export LISTINGSAPI_KEY="your-api-key"const client = new ListingsAPI();또는 비밀 정보 관리자에서 가져온 키를 전달합니다:
import { getSecret } from './secrets.js'; const apiKey = await getSecret('LISTINGSAPI_KEY');const client = new ListingsAPI({ apiKey });어느 쪽에서도 키를 찾지 못하면 생성자는 요청을 보내기 전에 즉시 AuthenticationError를 발생시킵니다.
기본 URL 재정의
클라이언트가 내부 프록시나 스테이징 환경에 연결하도록 설정합니다:
const client = new ListingsAPI({baseUrl: 'https://listings-proxy.internal.example.com',});끝에 붙은 슬래시는 자동으로 제거되므로 'https://listingsapi.com/'와 'https://listingsapi.com'는 동일하게 동작합니다.
제한 시간
각 시도에는 내부적으로 AbortSignal.timeout(timeout)가 적용되므로(Node 18 이상), SDK 호출에 별도로 AbortController를 적용할 필요가 없습니다. 기본 제한 시간은 시도당 240000 ms(4분)입니다.
시간이 초과된 시도는 연결 실패로 처리됩니다. 클라이언트는 남은 시도 횟수가 있는 동안 재시도하며, 최종 실패 시 APIConnectionError를 발생시킵니다. 지연 시간에 민감한 코드 경로에서는 제한 시간을 줄입니다:
const client = new ListingsAPI({ timeout: 15000 }); // 15 s per attempt자동 재시도
클라이언트는 상태가 429, 500, 502, 503, 504인 응답과 네트워크 수준의 장애(DNS 오류, 연결 거부, 시간 초과)에 대해 안전한 메서드인 GET, HEAD, OPTIONS만 재시도합니다. 0.3.2부터 쓰기(POST, DELETE)는 정확히 1번 전송되며, 실패하면 즉시 오류가 전달됩니다. 기본값인 maxRetries: 2을 사용하면 각 읽기는 최대 3번 시도됩니다.
v4 API는 Idempotency-Key를 지원하지 않고 중복 쓰기를 감지하지 않으므로, 시간이 초과되거나 5xx를 반환한 쓰기도 이미 커밋되었을 수 있습니다. 이를 확인 없이 재시도하면 사업장, 게시물 또는 리뷰 답글이 중복 생성됩니다. 쓰기를 반복하기 전에 직접 관리하는 키로 레코드를 다시 조회합니다.
각 재시도 전 대기 시간:
- 응답의
Retry-After헤더에 양수로 된 초 단위 값이 있으면 클라이언트는 정확히 그 시간만큼 기다립니다. - 그렇지 않으면 대기 시간이 지수적으로 증가합니다. 첫 번째 재시도 전에는 500 ms를 기다리고, 이후 재시도마다 대기 시간이 2배로 늘어납니다(1초, 2초 등).
네트워크 장애는 대기 시간 없이 즉시 재시도합니다. 시도 횟수를 모두 소진하면 마지막 응답은 타입이 지정된 오류(RateLimitError, InternalServerError 등, 오류 처리 참조)로 변환되며, 네트워크 장애로 시도 횟수를 모두 소진한 경우에는 APIConnectionError를 발생시킵니다.
// Fail fast and own the retry policy yourself:const client = new ListingsAPI({ maxRetries: 0 });사업장 ID
SDK에서 사업장 ID를 받는 모든 곳에서 숫자 ID는 API의 base64 형식(Location:<id>)으로 자동 인코딩되며, 이미 인코딩된 ID는 변경 없이 전달됩니다. 인코딩된 형식이 직접 필요한 경우를 위해 헬퍼가 내보내집니다:
import { encodeLocationId } from 'listingsapi-js'; encodeLocationId(16808); // 'TG9jYXRpb246MTY4MDg='encodeLocationId('TG9jYXRpb246MTY4MDg='); // returned as-is헤더 형식
모든 요청은 다음을 사용하여 인증됩니다:
Authorization: API <your-key>Content-Type: application/jsonSDK는 호출할 때마다 이 헤더들을 자동으로 설정합니다. 별도로 설정할 필요가 없습니다.
TypeScript 프로젝트 설정
SDK는 TypeScript를 우선으로 설계되었으며 타입이 포함되어 있으므로, 별도의 @types 패키지를 설치할 필요가 없습니다. 재현 가능한 빌드를 위해 버전을 고정합니다:
npm install listingsapi-js@0.3.2Node 18 이상 프로젝트에 필요한 최소 tsconfig.json 설정입니다:
{"compilerOptions": { "target": "ES2022", "module": "Node16", "moduleResolution": "Node16", "strict": true, "outDir": "dist"}}package.json에 "type": "module"가 설정된 ESM 프로젝트에서는 "module": "Node16"와 "moduleResolution": "Node16"을 사용합니다. CJS 프로젝트에서는 "module": "CommonJS"와 "moduleResolution": "Node"를 사용하면 됩니다. 패키지에는 두 빌드가 모두 포함되어 있으며, CommonJS 코드에서는 const { ListingsAPI } = require('listingsapi-js')로 패키지를 불러옵니다.
TypeScript 없이 사용하기
listingsapi-js는 런타임 의존성이 없는 일반 JavaScript로 컴파일됩니다. 빌드 단계 없이 .js 또는 .mjs 파일에서 가져올 수 있습니다:
import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI();const page = await client.fetchAllLocations({ first: 5 });for (const location of page.locations) {console.log(location.name, location.city); // Acme Dental Midtown}