TypeScript (Node)

Install

First things first, let’s install the TypeScript library!

(If you already installed the VSCode extension, the extension setup may have already installed the Tyepscript library.)

Run this command to ensure the TypeScript library is installed:

$ npm install polyapi

Important

PolyAPI requires a recent version of NodeJS. Head over to the Versions page to see the current supported versions.

Note

You may encounter an EACCESS error trying to npm install polyapi.

npm error [Error: EACCES: permission denied, open '/home/username/foo/package.json']
npm error The operation was rejected by your operating system.
npm error It is likely you do not have the permissions to access this file as the current user

These errors usually come from mixing sudo npm install and npm install commands.

If you are experiencing permission issues, PolyAPI recommends the following:

  • open a new terminal

  • create a new folder and cd into it

  • run npm init

  • run npm install polyapi WITHOUT sudo

In most cases, that should resolve the issues.

If you still see EACCESS issues, please read the npm error message carefully. Oftentimes the problem is with your npm cache and npm recommends the command you need to fix the cache permissions issues.

If you continue to experience issues, please email us at support@polyapi.io.

Setup and Generate

First configure your client:

$ npx poly setup

Enter your server and API Key when prompted.

Note

This command will also request for you to install/update some dependencies like ts-node and TypeScript.

Next, let’s go ahead and retrieve all the trained Poly functions and generate the TypeScript SDK for them:

$ npx poly generate

Warning

Please be sure to add node_modules to your .gitignore file.

Not only is it good practice in general, with PolyAPI your api key is stored in node_modules/.poly/.config.env so you can quickly run npx poly generate (and other commands) without having to re-enter your api key each time.

So be sure to add node_modules to your .gitignore file to avoid accidentally committing your api key to your git repo.

Deploy Your First Function

Next, let’s deploy our first custom function!

Helpful Resources

First 200 with Poly Video

Deploying an Integration to run on Poly Server Video

Open a new file called hello-world.ts and add the following code:

async function helloWorld(): string {
    return 'Hello Poly World!';
}

Next use the PolyAPI TypeScript SDK to deploy this function:

$ npx poly function add helloWorld ./hello-world.ts --context "myContext" --server

You should get back output like this:

Adding custom server side function... DEPLOYED
Function ID: 1111111-73ae-4463-aaa4-fdbdc9accd62
Generating TypeScript SDK...DONE

That’s it! You’ve now deployed your first server function!

Run First Function

Finally, let’s open a new file called index.ts and add the following code:

import poly from 'polyapi';

(async () => {
    console.log(await poly.myContext.helloWorld());
})();

Now run your file:

$ npx ts-node ./index.ts

The function will run and you should see “Hello Poly World!” printed in the console.

Client Function vs Server Function

In this example, we chose to make the function a “server function” with the --server option. This means the function will be deployed to and run on Poly’s FaaS (Functions as a Service) platform. If you invoke the function from your local machine:

  • an http request will be made to the Poly platform

  • the function will run on the Poly platform

  • the result will be sent back to your local machine via the http response

You can also use --client option to create a client function. Client functions are run directly in whatever client they are called in. So if you call them on your local machine, the code will run on your local machine. But if you call them inside a server function, the code will run on the FaaS platform in the context of that server function.

Generally speaking, client functions are used for things like small utility functions. They are just a way for you to better organize your code and share functionality between different server functions.

Server functions are standalone units of functionality that can be called from anywhere or scheduled to run at certain times or triggered by webhooks. They will generally call one or more api functions, perform some logic, and return a result.

Note

For client functions, you can choose to make your function async or not depending on what is appropriate.

For server functions, you can do the same, but in general, it is appropriate to make your server functions async so that you can use await to call other async functions. All API functions in the TypeScript Poly SDK are async and generally a server function will call at least one API function.

Glide Farther

Deploying one-off functions with npx poly function add is a good approach for smaller integration projects that run in a single environment (i.e. production) and won’t be updated frequently.

But it won’t scale well as you add more functions, multiple environments, and a team of people writing and deploying these functions.

To make building and deploying at scale easier, we’ve put together Project Glide, which lets you integrate PolyAPI more deeply into your git-based workflow backed by Github or Gitlab.

With a pre-commit hook in git, we can write functions and Poly will detect them automatically, validate them, and document them before we commit them.

And then once committed, the PolyAPI deployment action on Github or Gitlab picks up all our functions and deploys them to Poly.

See documentation in Project Glide to learn more and to setup this workflow.

Onward

That’s it! You have now:

  • Setup your Typescript SDK

  • Trained your first server function

  • Ran your first server function

This is the last step on the guided tour of Poly.

To further explore aspects of Poly and what it can do, head over to Next Steps.