New API library for internal API access

Hi everyone,

I've just released a Typescript/Javascript API for accessing the Cycle Internal API. This client makes it super easy for those already in the nodejs ecosystem to take advantage of it.

Check it out here.

and install it with:

npm install @cycleplatform/internal-api-client

Why would I want to do that?

Great question! The Internal API is a powerful little socket mounted into every container running on Cycle. It provides quick, direct access back to the platform to learn about its environment and even make changes to it.

Some of the things you can do include:

• Access time-locked scoped variables [API Docs]
• Scoped variables can have their access set to Internal API, with a time limit. That means your workloads can directly request scoped variables from within the container, and only for the specified time limit after the container starts.

import { getClient } from "@cycleplatform/internal-api-client";

const client = getClient();

const { data, error } = await client.GET("/v1/environment/scoped-variables");

if (error) {
  console.error(error);
} else {
  console.log(data);
}

• Submit custom metrics and events [API Docs]
• This is an up-and-coming feature that will be integrated into our new monitoring feature set the team is working on. You'll be able to record custom metrics and surface them in the portal.

import { getClient } from "@cycleplatform/internal-api-client";

const client = getClient();

const { data, error } = await client.POST("/v1/monitoring/metrics", {
  body: [
    {
      metric: "queue.depth",
      type: "gauge",
      labels: { queue: "ingest", region: "us-east" },
      tags: ["worker"],
      points: [
        {
          time: new Date().toISOString(),
          values: [42],
        },
      ],
    },
    {
      metric: "jobs.processed",
      type: "counter",
      points: [
        {
          time: new Date().toISOString(),
          values: [128],
        },
      ],
    },
  ],
});

if (error) {
  console.error(error);
} else {
  console.log(data);
}

• Reboot and power off the host [API Docs]
• If the container has the proper configuration options set (config.runtime.host.power_management), then it can reboot and power off the host. There may be some cool things you can do in a homelab setup with this.

import { getClient } from "@cycleplatform/internal-api-client";

const client = getClient();

const { data, error } = await client.POST("/v1/server/power/reboot");

if (error) {
  console.error(error);
} else {
  console.log(data);
}

• Much more
• There are a few more goodies hidden in the internal API. Let us know if you have any suggestions for new features, or want to showcase something cool you've built that uses it. If you run into any issues with the API client, please open an issue on the repo.

Thanks!