Customers SDK

완결된 작업은 Customers 가이드에서 시작하세요. 이 참조는 공개 SDK 경계를 설명합니다. import와 peer는 SDK 기본을 확인하세요.

출처 인식형 고객 그룹

신뢰할 수 있는 서버 워크플로에서는 고객이 그룹에 속한 권위 있는 출처를 조회하고 수동 출처만 추가하거나 회수할 수 있습니다:

import { createServerClient } from '@01.software/sdk/server'

type Server = ReturnType<typeof createServerClient>

export async function grantManualMembership(
  server: Server,
  input: { groupId: string; customerId: string; reason: string },
) {
  await server.customerGroups.grantMember(input)
  return server.customerGroups.listMembers({
    groupId: input.groupId,
    limit: 100,
  })
}

export async function revokeManualMembership(
  server: Server,
  input: { groupId: string; customerId: string },
) {
  await server.customerGroups.revokeMember(input)
  return server.customerGroups.listMembers({
    groupId: input.groupId,
    limit: 100,
  })
}

grantManualMembership은 수동 출처를 유지합니다. 그 출처를 제거하기로 명시적으로 결정했을 때만 별도 revokeManualMembership을 호출하세요. 추가 함수가 자동으로 회수하지 않습니다.

수동 출처를 회수해도 유효한 Membership 출처는 유지됩니다. customers.groups는 읽기 호환용 projection으로만 취급하고 출처 권위 활성화 이후에는 직접 쓰지 마세요.

고객 인증

새 스토어프론트의 기본 경로는 hosted customer OAuth입니다. 브라우저 안전 client에는 workspace publishable key와 customer auth issuer/client id를 함께 설정합니다:

import { createClient } from '@01.software/sdk'

// Consume this client in trusted routes with a server-owned token store.
export function createHostedCustomerClient(
  publishableKey: string,
  issuer: string,
  clientId: string,
) {
  return createClient({
    publishableKey,
    customer: { persist: false, oauth: { issuer, clientId } },
  })
}

신뢰할 수 있는 route handler에서 먼저 client.customer.oauth가 설정되어 있는지 guard한 뒤 createAuthorizationUrl()로 PKCE를 시작합니다. Callback code 교환도 서버에서 수행합니다. Access token, refresh token, transient OAuth state는 HttpOnly cookie나 서버가 소유한 session store에 보관하세요. Hosted customer OAuth token을 browser JavaScript, localStorage, client-readable cookie에 두지 마세요.

client.customer.auth.login()과 register()는 기존 direct email/password 호환성을 위해 남아 있습니다. 새 ecommerce template에서는 이 경로를 명시적인 legacy route 뒤에만 노출해야 합니다. Direct 세션은 await client.customer.auth.logoutAsync()로 refresh-token family를 서버에서 폐기합니다. 서버 요청이 실패해도 로컬 자격 증명은 지워지며, Promise가 거부되면 서버 로그아웃 미완료로 처리해야 합니다. 기존 동기 logout()은 로컬 상태만 지웁니다. useCustomerLogout()은 서버 폐기를 기다리고 성공·실패 모두에서 인증된 고객 query 데이터를 지웁니다. 이미 발급된 access token은 최대 15분 동안 유효할 수 있습니다. 워크스페이스 관리자는 콘솔의 고객 인증 설정에서 새 비밀번호 가입을 끌 수 있습니다. 이 경우 register()는 403 registration_disabled를 반환하며, 기존 고객의 비밀번호 로그인과 재설정은 유지됩니다.

이 direct local-auth 연동에서 client.customer.auth.forgotPassword(email)은 서명된 워크스페이스 webhook 전달과 플랫폼 관리 재설정 메일을 모두 지원합니다. 콘솔의 고객 인증 설정에서 전달 방식을 선택하고 storefront의 절대 재설정 URL을 설정하세요. 플랫폼 발송은 token query parameter를 추가하고, 검증된 워크스페이스 발신자가 있으면 이를 사용합니다. 이 호출에는 임의 redirect URL을 전달할 수 없습니다.

고객 셀프 탈퇴

비밀번호가 있는 로그인 계정에서 client.customer.auth.withdraw(currentPassword)를 호출합니다. 성공 시 SDK 인증 정보가 지워지며 앱의 세션 쿠키와 캐시도 지워야 합니다. active_membership_exists, reauthentication_unavailable (409)과 account_locked (423)을 처리하세요. 계정·오류·보존 동작의 자세한 내용은 SDK README를 참고하세요.

Hosted 세션 메서드

customer.oauth는 optional이므로 createAuthorizationUrl, parseCallback, exchangeCode, refresh, logout 전에 설정을 검사하세요. parseCallback에는 저장한 expectedState, exchange에는 원래 PKCE verifier와 등록 redirect URI를 전달합니다. 교환 뒤 trusted client에 access token을 설정하고 customer.auth.me()로 identity를 readback합니다. 회전을 직렬화하고 하나의 server-owned access/refresh pair를 보존하세요.

Hosted logout의 success는 요청 수락이며 sweep 여부를 관찰했다는 뜻이 아닙니다. 같은 tenant·client에 발급된 미만료 refresh token으로 인식되면 회전 또는 family 철회 뒤에도 sweep합니다. token이 없거나 만료됐거나 다른 client에 묶였으면 sweep하지 않으며 앱은 결과를 구분할 수 없습니다. sweep은 legacy-direct를 포함한 해당 tenant의 그 고객 client들을 대상으로 합니다. fence 이후 family 보존은 같은 durable intent의 서버 내부 재시도에만 적용됩니다. 쿠키 정리와 revocation_unconfirmed 처리는 완전한 로그인·로그아웃 작업을 따르며 cleanup 실패가 원래 오류를 덮지 않아야 합니다.

다음 액션

• SDK
• Webhooks