Skip to content

Latest commit

 

History

History
174 lines (136 loc) · 7.32 KB

README.md

File metadata and controls

174 lines (136 loc) · 7.32 KB

foundry-platform-typescript

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.

Using the Platform SDKs

Installation

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/foundry

Creating the Client

All 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);

Using the Platform SDKs

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)

Hello world example

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:

  1. Copy the above HTML into an editor and save it as (for example) ~/Desktop/test-website/index.html.
  2. In Foundry, open the Developer Console and create a new third-party application for your web app. Set http://localhost:8080 as a redirect URL (do not include a path like /auth/callback).
  3. Copy your client ID and Foundry hostname into the spaces labeled TODO in the code.
  4. In terminal, run cd ~/Desktop/test-website.
  5. Start a web server to serve the file by running python3 -m http.server 8080 (or your preferred web server).
  6. Navigate to http://localhost:8080 in your browser and authenticate your app with Foundry.
  7. Enjoy being greeted by name!

Dev workflow

  1. Fork the repo

  2. Create a branch

  3. pnpm install

  4. Start dev mode: pnpm dev

  5. Add your code

  6. Add a changeset

    📘 Note Follow semver rules here.

    1. Assuming you've run pnpm install, run changeset (or pnpm exec changeset).
    2. 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)
    3. Select the packages you want the changeset applied to using the arrow keys (up/down) and space-bar to "select" the package.
    4. Press enter to continue.
    5. The CLI will go through a progression of asking you which packages you previously selected need a major bump? Then a minor bump? Patch bumps assumed for remaining packages changed. Arrows and space bar to select. Enter to continue (even if you selected nothing).
    6. Enter a change (or press enter on empty to open your editor.)

    Info Full docs on the changesets tool can be found at the changesets/changesets github repo.

  7. If you're curious what the final build output might look like you can run pnpm build from root.

  8. Run all lint rules and tests with pnpm check from root.