The Foundry Platform SDK for Typescript is an SDK for the APIs listed in the Foundry API documentation. Packages are available on NPM for each API namespace as @osdk/foundry.{namespace}. The SDK can be used either with an Ontology SDK client (for easy use alongside a generated Ontology SDK) or with a standalone platform SDK client.
You can install the package for a specific namespace.
npm install @osdk/foundry.{namespace}Alternatively, you can install all API namespaces from a single package.
npm install @osdk/foundryAll of the Platform SDK endpoints will require a client to be passed in. The client can be created via a method exported from the @osdk/client npm package.
To create your client, you will need to create an application in the Developer Console app on your Foundry stack. You will need the client ID as well as the base url of your foundry stack and a redirect URL that you can configure in Developer Console.
Note that creating a client this way means that your client is not tied to a specific ontology, and can be used across different ontologies on your stack.
import { createPlatformClient } from "@osdk/client";
import { createPublicOauthClient } from "@osdk/oauth";
const stack =
"<TODO: hostname of your Foundry instance, e.g. https://foundry.example.com>";
// Your OAuth2 client ID from Developer Console.
const clientId =
"<TODO: OAuth2 client ID from the Developer Console overview page>";
// The URL of your app you want to redirect to
const redirectUrl = "http://localhost:8080";
const auth = createPublicOauthClient(clientId, stack, redirectUrl);
const client = createPlatformClient(stack, auth);Alternatively, if you want to create a client to be used alongside the TypeScript Ontology SDK, you will need an ontology RID as well.
import { createClient } from "@osdk/client";
const ontologyRid =
"<TODO: The RID of your ontology. You can find this in the Ontology Manager application>";
const client = createClient(stack, ontologyRid, auth);Below is an example of how to use your installed SDK and client to hit a Foundry endpoint.
import { Users } from "@osdk/foundry.admin"
const client = //Client created above
const currentUser = await Users.getCurrent(client, { preview: true });
console.log(currentUser)The following is a complete, annotated example of a "hello, world" web app using the Platform SDK to greet users by name.
<!DOCTYPE html>
<html>
<head>
<title>Hello world!</title>
<!-- Load dependencies from a CDN. In production, most developers use a dependency and build
system like npm instead. -->
<script type="importmap">
{
"imports": {
"vue": "https://cdn.jsdelivr.net/npm/[email protected]/dist/vue.esm-browser.min.js",
"@osdk/client": "https://cdn.jsdelivr.net/npm/@osdk/[email protected]/+esm",
"@osdk/oauth": "https://cdn.jsdelivr.net/npm/@osdk/[email protected]/+esm",
"@osdk/foundry.admin": "https://cdn.jsdelivr.net/npm/@osdk/[email protected]/+esm"
}
}
</script>
</head>
<body>
<h1>Hello world!</h1>
<!-- The contents of our vue app. -->
<div id="app">
<!-- Suspense handles the fact that Greeting is an async component, since it needs to wait on
the network to load our name and greet us. -->
<Suspense>
<!-- Greeting is the main component of our app, defined below. -->
<Greeting />
</Suspense>
</div>
<script type="module">
import { createApp } from "vue"
// Create a standalone platform SDK client. Users can also use an OSDK client created with
// `createClient` if they have an Ontology SDK.
import { createPlatformClient } from "@osdk/client"
// Create a public OAuth2 client. OSDK clients and Platform SDK clients use the same auth
// client types.
import { createPublicOauthClient } from "@osdk/oauth"
// The admin endpoints, which include our getCurrentUser endpoint.
import { Users } from "@osdk/foundry.admin"
// The hostname of your Foundry instance, like `https://foundry.example.com`.
const stack = "<TODO: hostname of your Foundry instance, e.g. https://foundry.example.com>";
// Your OAuth2 client ID from Developer Console.
const clientId = "<TODO: OAuth2 client ID from the Developer Console overview page>";
// The URL of your app (this HTML page).
const redirectUrl = "http://localhost:8080";
const auth = createPublicOauthClient(clientId, stack, redirectUrl);
const client = createPlatformClient(stack, auth);
createApp({})
.component('Greeting', {
// Use the Platform SDK to call the getCurrentUser endpoint with the client we created.
// Await the result before rendering the greeting template below.
async setup() {
return {
user: await Users.getCurrent(client, { preview: true }),
}
},
template: `<p>Hello, <b>{{ user.givenName }}</b>!</p>`
})
.mount('#app');
</script>
</body>
</html>To run this example, do the following:
- Copy the above HTML into an editor and save it as (for example)
~/Desktop/test-website/index.html. - In Foundry, open the Developer Console and create a new third-party application for your web app. Set
http://localhost:8080as a redirect URL (do not include a path like/auth/callback). - Copy your client ID and Foundry hostname into the spaces labeled
TODOin the code. - In terminal, run
cd ~/Desktop/test-website. - Start a web server to serve the file by running
python3 -m http.server 8080(or your preferred web server). - Navigate to
http://localhost:8080in your browser and authenticate your app with Foundry. - Enjoy being greeted by name!
Note: some of these workflows are internal to Palantir. It is not expected that external developers will be able to perform all of the below workflows.
- Fork the repo
- Create a branch
- Palantir-internal developers only: copy
.envrc.sampleinto.envrcand populate the variables - Run
source .envrc(if necessary) pnpm install- Start dev mode:
pnpm dev - Add your code
- Add a changeset
- Assuming you've run
pnpm install, runchangeset(orpnpm exec changeset). - The tool will split things into changed vs unchanged packages (which you may need if you decide to add changeset logs in a future PR for past features)
- Select the packages you want the changeset applied to using the arrow keys (up/down) and space-bar to "select" the package.
- Press enter to continue.
- Select which packages need major/minor/patch bumps. Typically you should not select anything here and always use patch bumps. We will then bump the major and minor version separately as needed.
- Enter a change (or press enter on empty to open your editor.)
- Assuming you've run
- If you're curious what the final build output might look like you can run
pnpm buildfrom root. - Run all lint rules and tests with
pnpm checkfrom root.
- Follow the dev workflow above
- Run
scripts/getOpenApiIr.sh - Run
scripts/generatePlatformSdk.sh - Remember to add a changeset (following the instructions above)
- Commit and open a PR
- Follow the dev workflow above
- Edit
packages/docs-spec-sdk/src/spec.ts - Remember to add a changeset (following the instructions above)
- Commit and open a PR
- Follow the dev workflow above
- Run
scripts/createReleasePr.sh - Merge the PR (Github Actions will publish it)