Chapter 8: The Server SDK

In Progress

This part of the tutorial is still in the process of being written.

The Server SDK allows your business to unlock the full potential of the ALANA Platform by enabling you to access what we call protected APIs. These APIs offer the same functionality as your ALANA Dashboard, such as creating your own memberships, products, or Coins, but they can be used in your own applications. You still have the Platform as your foundation, but everything else is up to you.

This brings both additional complexities and numerous benefits. The Server SDK requires more development effort on your part, for example, because these APIs can't be accessed through the normal browser means. In other words, the Server SDK is a vital component of a full-stack ALANA application.

What you get in return is full power over your data, without the need for the Dashboard. In fact, using the Server SDK, you could create your own Dashboard, your own businesses, your own Coins...your own ALANA Platform!

Client vs server

The biggest change in thinking when you use the Server SDK comes from its server-only nature. All protected APIs require the use of your ALANA API secret key, rather than the public key you've been using until now. On top of that, to use anything in the protected segment of the API, you must have a valid access token. In other words, you must be logged in.

Creating an instance

You can access the Server SDK by creating a new instance. It's almost exactly the same process as when we created the SDK instance all the way back in Part 1.

const ServerApi = Alana({
    server: true,
    apiUsername: API_USERNAME,
    mode: 'development',
}, API_SECRET_KEY);

The key differences are:

1. You must set the server option to true to create a Server SDK instance.
2. The API secret key is passed to the creation function as a separate parameter, not in the apiKey option.
3. The function will throw an error if it detects that you're running it in a browser in production mode.

Keeping you safe

The Client and Server SDKs are in the same package because they share so much code and structure that implementing them separately would have been too costly. This means that you'll still have the code for the Server parts even if you're using the SDK in a browser. You may be tempted to create a Server SDK instance in a browser environment.

We don't want you to risk exposing your API secret key, but we also know how difficult it can be to spin up a "simple" full-stack app. Thus, we allow you to create Server SDK instances within the browser in development and sandbox modes, so you can get a feel for how the components work. In production mode, however, the instance creator function will throw an error.

The protected API

A simple app

It's difficult to convey a "simple" full-stack app of any kind, let alone one that fits with Bianca's needs, but let's try it anyway. Say that Bianca wants to allow her members to purchase a special Inner Circle Coin she has created as a way to raise additional funds for expanding Inner Light.

1. Create the project

We'll use Hono as a convenient and fast micro-framework to get up and running. (If you prefer Express, Fastify, or something else, feel free to use those instead.)

To start, we'll create a new project using Hono's Node template, and also install its dependencies.

npm create hono@latest inner-light-server -- --template nodejs --install
cd inner-light-server

Next, let's add the ALANA SDK as a dependency. Following the instructions in Installation, we create a file called .npmrc containing this line:

@collectivtech:registry=https://npm.pkg.github.com

Then we install the SDK:

npm install @collectivtech/alana-sdk-js

2. Start the dev server

Hono has a dev server that will watch your source files and reload if they are changed. So let's start that.

npm run dev

Dev servers are for development

Don't use the dev server for production deployment, because it's nowhere near as robust as a real web server or hosting environment. If you want to continue using Hono, think about where you're going to deploy your app (e.g., AWS Lambda, Vercel) and choose the right adapter.

If you're building with a different server framework like Express or Nextjs, that framework's documentation should have guides on how to deploy for production. The ALANA SDK is almost completely dependency-free, so it should not interfere or require any changes to your deployment recipe of choice.

3. Create the SDK instance

Now, let's create an index.ts file inside a src/ directory of our new project.

4. Set up an API

5. Serve a page

6. Build it bigger

Conclusion