기존 TypeScript 앱에 OSDK 설치

이 절차는 공개 OAuth를 사용하는 Client-facing 앱에 적용합니다. 서비스 사용자와 client secret은 서버 앱에서만 사용합니다. 먼저 Developer Console에 앱을 만들고 SDK를 생성합니다.

레지스트리와 토큰

Node 18 이상이 필요하며 실제 프레임워크의 더 높은 요구 조건도 확인합니다. 패키지 다운로드용 FOUNDRY_TOKEN은 환경에 제공하고 코드에는 넣지 않습니다.

프로젝트 또는 사용자 .npmrc에 생성 SDK의 범위와 레지스트리를 지정합니다. 다음은 가상 호스트와 패키지 범위의 형식 예이며 Developer Console Overview의 실제 값으로 바꿉니다.

//hostname.palantirfoundry.com/artifacts/api/:_authToken=${FOUNDRY_TOKEN}
@example-osdk:registry=https://hostname.palantirfoundry.com/artifacts/api/repositories/ri.artifacts.main.repository.45660bd6-de33-442e-9f48-a0c02372b906/contents/release/npm

${FOUNDRY_TOKEN}은 그대로 파일에 두고 비밀값은 npm 실행 환경에서 치환합니다. 범위 키에는 /sdk를 붙이지 않습니다.

404가 나면 실제 패키지 레지스트리와 @scope:registry 설정을 확인합니다. npm config get registry는 일반 레지스트리만 보여 주므로 범위별 설정도 확인해야 합니다. 프로젝트, 사용자 및 전역 .npmrc의 의도하지 않은 override를 찾아 그 설정만 정리합니다. 기존 전체 레지스트리 설정을 무조건 삭제하지 않습니다.

인증서와 설치

조직의 사용자 CA가 필요하면 Node가 인증서 파일을 읽도록 설정합니다. CA_BUNDLE에는 실제 완전한 CA 체인 파일 경로를 미리 제공합니다.

: "${CA_BUNDLE:?조직 CA 번들 파일 경로가 필요합니다}"
export NODE_EXTRA_CA_CERTS="$CA_BUNDLE"

사용자 CA가 필요하지 않으면 이 단계는 생략합니다. 패키지 설치는 다음과 같습니다.

: "${FOUNDRY_TOKEN:?SDK 다운로드 토큰이 필요합니다}"
: "${OSDK_PACKAGE:?실제 생성 SDK 패키지 이름이 필요합니다}"
export FOUNDRY_TOKEN
npm install "$OSDK_PACKAGE@latest" @osdk/client@latest @osdk/oauth@latest

공개 OAuth 클라이언트

기존 앱의 공개 설정에서 clientId, foundryUrl, redirectUrl과 ontologyRid를 받아 클라이언트를 만듭니다. 다음 helper를 client.ts에 둘 수 있습니다.

import { createPublicOauthClient } from "@osdk/oauth";
import { createClient } from "@osdk/client";

export interface FoundryBrowserConfig {
    clientId: string;
    foundryUrl: string;
    redirectUrl: string;
    ontologyRid: string;
}

export function createFoundryBrowserClient(config: FoundryBrowserConfig) {
    const auth = createPublicOauthClient(config.clientId, config.foundryUrl, config.redirectUrl, {
        scopes: ["api:use-ontologies-read"],
    });
    return createClient(config.foundryUrl, config.ontologyRid, auth);
}

예제는 읽기만 요청합니다. 쓰기 등 필요한 작업은 앱 제한 및 요청 scope에 맞춥니다. 앱 루트에서 이 helper를 한 번 호출한 클라이언트를 유지하며 렌더마다 새로 만들지 않습니다.

auth는 Client에 전달한 토큰 제공자입니다. SDK가 토큰을 요청하면 유효한 토큰을 사용하거나 OAuth 갱신 및 로그인 리다이렉트를 처리합니다. 리다이렉트 URI에서 앱을 다시 로드할 수 있어야 하며 등록 URI 및 CORS와 일치해야 합니다.

React에서 첫 페이지 표시

가상의 @example-osdk/sdk에는 Country와 countryName이 있다고 가정합니다. 클라이언트를 props로 받으므로 기존 앱의 설정 및 라우터에 연결할 수 있습니다. 콜백 경로에서도 같은 인증 구성을 유지합니다.

import { useEffect, useState } from "react";
import type { Client, Osdk } from "@osdk/client";
import { Country } from "@example-osdk/sdk";

export function CountryList({ client }: { client: Client }) {
    const [countries, setCountries] = useState<Osdk.Instance<Country>[] | undefined>();
    const [error, setError] = useState<string | undefined>();

    useEffect(() => {
        let cancelled = false;
        setCountries(undefined);
        setError(undefined);
        client(Country).fetchPage({ $pageSize: 10 }).then(page => {
            if (!cancelled) setCountries(page.data);
        }).catch(reason => {
            if (!cancelled) setError(reason instanceof Error ? reason.message : String(reason));
        });
        return () => { cancelled = true; };
    }, [client]);

    if (error !== undefined) return <p role="alert">{error}</p>;
    if (countries === undefined) return <p>조회 중입니다.</p>;
    if (countries.length === 0) return <p>조건에 맞는 국가가 없습니다.</p>;
    return <ul>{countries.map(country =>
        <li key={country.$primaryKey}>{country.countryName ?? country.$primaryKey}</li>
    )}</ul>;
}

최대 열 개의 첫 페이지를 표시합니다. 요청 오류는 빈 목록으로 바꾸지 않고 별도 상태로 보여 줍니다. countryName이 없으면 실제 기본 키를 표시합니다.

React 훅과 기본 UI

선택적으로 @osdk/react의 타입 훅과 공통 캐시를 사용하거나 @osdk/react-components의 기본 UI를 추가할 수 있습니다. 전자는 후자의 기반이며 호환되는 @osdk 패키지를 함께 사용해야 합니다.

npm install @osdk/react@latest @osdk/react-components@latest

생성 템플릿이 아닌 기존 앱은 루트 OsdkProvider를 구성해야 합니다. 앱을 Foundry에 패키징할 때 환경별 설정을 자동 매핑하려면 메타 태그 기반 초기화, SDK 없이 초기화한 표준 저장소의 변경 지점은 앱에 OSDK 추가를 따릅니다.