Events SDK
이벤트의 canonical 날짜와 유료 입장권 projection 참조.
완결된 작업은 Events 가이드에서 시작하세요. 이 페이지는 공개 Events SDK를 설명합니다. import와 peer는 SDK 기본을 참고하세요.
이벤트 범위와 종일 날짜
client.events.getRange()는 종일 이벤트와 회차마다 allDayStartDate와 종료일 미포함인 allDayEndDateExclusive를 반환합니다. isAllDay가 true이면 이 날짜 쌍을 표시하세요. 종일 항목의 시각 필드는 호환성과 색인을 위해 남긴 현지 자정 값이므로, 보는 사람의 시간대로 바꿔 표시 날짜를 구하지 마세요. 시간이 정해진 항목은 startsAt, endsAt을 쓰며 두 날짜 필드는 null입니다.
목록과 링크 공개 이벤트
client.events.getRange()는 visibility=public인 게시된 이벤트를 나열합니다. 페이지와 전체 개수에서 unlisted 이벤트를 제외하며, Publishable Key로 조회하는 원시 이벤트와 회차 목록 및 개수도 같은 규칙을 따릅니다. 링크 공개 이벤트는 이벤트와 회차 ID를 보관한 뒤 client.collections.from('events').findById(eventId)와 client.collections.from('event-occurrences').findById(occurrenceId)로 각각 조회하세요. 이벤트와 회차가 등록 조건을 충족하면 계속 등록할 수 있습니다.
원시 목록에 ID나 slug 필터를 넣어도 목록 공개 규칙을 따릅니다. 이벤트를 목록에 노출하려면 visibility=public을 선택하세요. 서버의 목록 동작이 바뀌면 캐시된 목록과 전체 개수를 새로 조회하세요.
이벤트 입장권
client.events.getAdmissionAvailability({ occurrence })로 한 회차의 공개 유료 입장권 선택지를 표시합니다.
import { createClient } from '@01.software/sdk'
type Client = ReturnType<typeof createClient>
export async function readAdmissionChoices(client: Client, occurrence: string) {
const admission = await client.events.getAdmissionAvailability({ occurrence })
if (admission.admissionTypes.length === 0) {
return { kind: 'empty' as const, admission }
}
return { kind: 'choices' as const, admission }
}응답에는 이벤트와 회차, 입장권 유형, 기존 Cart 흐름에 쓸 productId와 variantId, 공개 가격, 남은 정원 힌트가 있습니다. 입장권 유형 행마다 요청한 occurrenceId가 들어 있으며, 이벤트 전체에 적용되는 유형도 마찬가지입니다. 원시 priceReference, 상품 재고, 보류, Checkout·주문 기록, 결제 세션, 결제사 이벤트 id, 내부 주문 금액은 포함하지 않습니다.
구매는 Ecommerce 도우미로 합니다. 반환된 상품과 변형을 admissions: [{ eventId, occurrenceId, admissionTypeId }]와 함께 Cart에 추가한 뒤 Cart → Checkout → PaymentSession 흐름을 따르세요. 이 도우미는 이벤트 커머스가 쓰는 events.products 데이터와 별개입니다.
Cart 항목의 입력과 응답은 admissions를 씁니다. 단수형 admission은 없습니다.
{ occurrence, market: 'kr' }처럼 market에 활성 마켓의 핸들이나 ID를 전달합니다. 생략하면 기본 마켓을 사용합니다. 가격에는 해당 마켓의 통화와 ID가 포함되며, 마켓 고정가가 있으면 고정가를, 없으면 계산 가격을 반환합니다. 없는 마켓은 404 not_found를 반환합니다. 같은 마켓으로 장바구니를 만들면 표시 가격과 구매 단가를 맞출 수 있습니다. Checkout은 현재 가격을 다시 조회합니다.
마켓이 해석되면 같은 워크스페이스의 상품이 해당 마켓에 지정된 입장권만 반환합니다. market을 생략해 기본 마켓을 사용하는 기존 호출에도 이 필터가 적용됩니다. 상품이 없거나 마켓 지정이 비어 있으면 해당 입장권은 제외됩니다. 활성 마켓이 없으면 기존처럼 기본 가격과 필터하지 않은 응답을 유지합니다.
범위와 무료 등록 메서드
getRange는 등록 정책 정보가 담긴 이벤트와 회차를 반환합니다. register는 무료 등록을 제출하며, 비회원 조회와 취소에는 반환된 비회원 자격 증명을 씁니다. 취소하면 그 자격 증명이 폐기되므로 그것으로 비회원 조회 화면에 리디렉션하지 마세요. 전체 조회·등록·관리 흐름과 앱이 정하는 로그인 조건은 Events 가이드에서 다룹니다. 유료 입장권은 이벤트 입장권의 별도 Cart·Checkout 흐름을 씁니다.
내 이벤트 등록 내역
고객이 로그인한 뒤 client.events.listMyRegistrations({ page: 1, limit: 10 })를 호출하세요. 고객 JWT와 events가 켜진 같은 워크스페이스의 Publishable Key가 필요하며, 서버 키나 운영자 세션으로 고객을 대신할 수 없습니다.
page기본값은 1입니다.limit기본값은 10이고 최대 100입니다.- 결과에는
docs,totalDocs,limit,page,totalPages,hasNextPage,hasPrevPage가 있습니다. - 각 등록에는 참조, 공개 제목과 시간, 등록·참석 상태, 수량, 생성 시각이 있습니다. 없거나 공개되지 않은 정보는
null이지만 참조와 상태는 남습니다. 개인정보가 만료되거나 정리돼도 형태는 같습니다. - 비회원 자격 증명, 참석자 정보와 답변, 감사 필드, 장소는 포함하지 않습니다. 모든 응답은
no-store이며, 이메일이 같은 비회원 등록은 연결되지 않습니다.
createServerClient().events에는 이 고객 전용 메서드가 없습니다. 서버 BFF는 요청마다 고객 JWT로 createClient({ publishableKey, customer: { persist: false, token } }) 클라이언트를 만들고 client.events.listMyRegistrations()를 호출합니다.
다음 액션
등록 이메일 확인
등록 이메일 확인을 켠 이벤트는 먼저
client.events.requestRegistrationEmailVerification(input)을 호출합니다.
verificationRequired가 true면 이메일로 받은 8자리 코드를 입력받고, 같은 input에
emailVerification: { requestId, code }를 추가해 client.events.register를 호출합니다.
코드는 15분 동안 유효하며 5회까지 시도할 수 있습니다. 확인과 정원 재검사가 성공하기
전에는 등록과 좌석이 만들어지지 않습니다. 설정을 끈 이벤트는 즉시 등록됩니다.
확정 메일은 워크스페이스와 수신자별 최근 60분 동안 10회까지 발송하며, 초과해도 등록은
유지됩니다. 행사 취소 통지는 제외합니다. 확인 메일은 별도로 시간당 3회, 재발송 간격
60초를 적용하며 일반 이메일 발송 quota도 사용합니다.
Live와 Sandbox 모두 실제 발송 전에 처리 접수 응답을 반환합니다. 접수는 메일 전달이나
좌석 확보를 뜻하지 않습니다. Sandbox에서는 해당 워크스페이스의 현재 활성 멤버가
인증한 본인 이메일로만 코드를 보냅니다. 플랫폼 발신자와 [Sandbox] 제목을 사용하고
Reply-To는 제거합니다. 다른 수신자와 일반 이벤트 메일은 capture하며 공개 접수 응답은
동일합니다. Sandbox는 월 100회의 비과금 이메일 한도를 함께 사용합니다.
수신자 한도에 걸리면 발송만 억제하고 같은 접수 응답을 반환합니다. 수신자와 무관한
워크스페이스 입장 제한은 동기 429로 유지합니다. 억제 결과는 운영자 로그에
recipient_verification_limit로 남습니다.