Interval

The Interval class is the entrypoint for defining actions and pages.

Usage

TypeScript

import path from "path";
import { Interval } from "@interval/sdk";

const interval = new Interval({
  apiKey: "<YOUR API KEY>" // get an API key at https://interval.com/dashboard/develop/keys
  routesDirectory: path.resolve(__dirname, "routes"),
});

interval.listen();

JavaScript

const path = require("path");
const { Interval } = require("@interval/sdk");

const interval = new Interval({
  apiKey: "<YOUR API KEY>" // get an API key at https://interval.com/dashboard/develop/keys
  routesDirectory: path.resolve(__dirname, "routes"),
});

interval.listen();

Python

import os
from interval_sdk import Interval

interval = Interval(
    api_key=os.environ["INTERVAL_API_KEY"],
)

interval.listen()

Props

TypeScript

apiKey

Required

string

Your API key. Get yours at https://interval.com/dashboard/develop/keys.

routesDirectory

Optional

string

The path to the directory of route definitions when using file-based routing.

routes

Optional

Record<string, Action | Page>

An object mapping string route slugs to Actions or Pages when defining routes inline.

logLevel

Optional

"quiet" | "info" | "debug"

Controls the type of logs emitted by Interval in the console's standard out and standard error. Defaults to 'info', set to 'quiet' to reduce output to only fatal errors, and 'debug' to include low-level internal debugging information.

sendTimeoutMs

Optional

number

How long to wait in milliseconds before timing out the initial call to Interval, increasing linearly for each subsequent retry attempt. Defaults to 5000 (5 seconds).

retryIntervalMs

Optional

number

How long to wait in milliseconds before retrying the initial failed call to Interval, increasing linearly for each subsequent retry attempt. Defaults to 3000 (3 seconds).

maxResendAttempts

Optional

number

The number of resend attempts that will be made before abandoning a call to Interval. Defaults to 10.

pingIntervalMs

Optional

number

How often in milliseconds Interval is pinged to ensure a consistent connection. Defaults to 30000 (30 seconds).

pingTimeoutMs

Optional

number

How long to wait in milliseconds for an attempted ping to Interval before assuming it fails and trying again. Defaults to 5000 (5 seconds).

closeUnresponsiveTimeoutMs

Optional

number

How long to wait in milliseconds after receiving the last successful ping response before closing the connection and attempting to reconnect. Defaults to 180000 (3 minutes).

reinitializeBatchTimeoutMs

Optional

number

How long to wait in milliseconds before updating Interval with any programmatic changes made to defined routes. Defaults to 200.

onError

Optional

(props: IntervalErrorProps) => void

A global error callback, typically used for logging or reporting to error services.

(props: {
    error: Error | unknown
    route: string
    routeDefinition: Action | Page | undefined
    params: Record<string, string | number | boolean | null | undefined | Date | bigint>
    environment: 'production' | 'development' | string
    user: {
        email: string
        firstName: string | null
        lastName: string | null
    }
    organization: {
        name: string
        slug: string
    }
}) => void

JavaScript

apiKey

Required

string

Your API key. Get yours at https://interval.com/dashboard/develop/keys.

routesDirectory

Optional

string

The path to the directory of route definitions when using file-based routing.

routes

Optional

Record<string, Action | Page>

An object mapping string route slugs to Actions or Pages when defining routes inline.

logLevel

Optional

"quiet" | "info" | "debug"

Controls the type of logs emitted by Interval in the console's standard out and standard error. Defaults to 'info', set to 'quiet' to reduce output to only fatal errors, and 'debug' to include low-level internal debugging information.

sendTimeoutMs

Optional

number

How long to wait in milliseconds before timing out the initial call to Interval, increasing linearly for each subsequent retry attempt. Defaults to 5000 (5 seconds).

retryIntervalMs

Optional

number

How long to wait in milliseconds before retrying the initial failed call to Interval, increasing linearly for each subsequent retry attempt. Defaults to 3000 (3 seconds).

maxResendAttempts

Optional

number

The number of resend attempts that will be made before abandoning a call to Interval. Defaults to 10.

pingIntervalMs

Optional

number

How often in milliseconds Interval is pinged to ensure a consistent connection. Defaults to 30000 (30 seconds).

pingTimeoutMs

Optional

number

How long to wait in milliseconds for an attempted ping to Interval before assuming it fails and trying again. Defaults to 5000 (5 seconds).

closeUnresponsiveTimeoutMs

Optional

number

How long to wait in milliseconds after receiving the last successful ping response before closing the connection and attempting to reconnect. Defaults to 180000 (3 minutes).

reinitializeBatchTimeoutMs

Optional

number

How long to wait in milliseconds before updating Interval with any programmatic changes made to defined routes. Defaults to 200.

onError

Optional

(props: IntervalErrorProps) => void

A global error callback, typically used for logging or reporting to error services.

(props: {
    error: Error | unknown
    route: string
    routeDefinition: Action | Page | undefined
    params: Record<string, string | number | boolean | null | undefined | Date | bigint>
    environment: 'production' | 'development' | string
    user: {
        email: string
        firstName: string | null
        lastName: string | null
    }
    organization: {
        name: string
        slug: string
    }
}) => void

Python

api_key

Required

str

Your API key. Get yours at https://interval.com/dashboard/develop/keys.

log_level

Optional

"quiet" | "info" | "debug"

Controls the type of logs emitted by Interval in the console's standard out and standard error. Defaults to 'info', set to 'quiet' to reduce output to only fatal errors, and 'debug' to include low-level internal debugging information.

send_timeout

Optional

number

How long to wait in seconds before timing out the initial call to Interval, increasing linearly for each subsequent retry attempt. Defaults to 5 seconds.

retry_interval

Optional

float

How long to wait in seconds before retrying a failed call to Interval. Defaults to 3 seconds.

max_resend_attempts

Optional

number

The number of resend attempts that will be made before abandoning a call to Interval. Defaults to 10.

ping_interval

Optional

float

How often in seconds Interval is pinged to ensure a consistent connection. Defaults to 30 seconds.

ping_timeout

Optional

float

How long to wait in seconds for an attempted ping to Interval before assuming it fails and trying again. Defaults to 5 seconds.

reinitialize_batch_timeout

Optional

float

How long to wait in seconds before updating Interval with any programmatic changes made to defined routes. Defaults to 0.2 seconds.

on_error

Optional

(props: IntervalErrorProps) => None

A global error callback, typically used for logging or reporting to error services.

@dataclass
class ContextUser:
    email: str
    first_name: str | None
    last_name: str | None

@dataclass
class OrganizationDef:
    name: str
    slug: str

@dataclass
class IntervalErrorProps:
    error: BaseException
    route: str
    route_definition: Action | Page | None
    environment: Literal["production", "development"] | str
    params: dict[str, bool | int | float | str | datetime | date | time | None]
    user: ContextUser
    organization: OrganizationDef

Methods

TypeScript

listen()

Establish the persistent connection to Interval.

async ping()

Ping Interval to manually ensure an active connection, useful for health chceks. Will return `true` if successful, throw a `NotConnectedError` if there is no active connection, or throw a `TimeoutError` if a response is not received within `pingTimeoutMs`.

async safelyClose()

Safely close the connection to Interval, preventing new actions from being launched and closing the persistent connection afterward. Resolves when the connection is successfully safely closed.

immediatelyClose()

Immediately terminate the connection to interval, terminating any actions currently in progress.

async enqueue(slug, { assignee, params })

Enqueue an action to be completed, with an optional `assignee` email to assign the action to, and optional `params` which will be passed to the action as `ctx.params`. Assigned actions will be displayed in users' dashboards as a task list. See Queued actions for more information.

async (
  slug: string,
  options?: {
    assignee?: string,
    params?: Record<string, string | number | boolean | Date | null | undefined>
  }
) => Promise<{
  id: string;
  assignee?: string;
  params?: Record<string, string | number | boolean | Date | null | undefined>;
}>

async dequeue(queuedActionId)

Dequeue a previously enqueued action which was created with `interval.enqueue()`. See Queued actions for more information.

async (
  queuedActionId: string
) => Promise<void>

async notify(config)

Sends a custom notification to Interval users via email or Slack. To send Slack notifications, you'll need to connect your Slack workspace to the Interval app in your organization settings. See Notifications for more information.

async ({
  message: string,
  title?: string,
  delivery?: {
    to: string;
    method?: 'SLACK' | 'EMAIL';
  }[],
  transactionId?: string,
  idempotencyKey?: string,
}) => Promise<void>

JavaScript

listen()

Establish the persistent connection to Interval.

async ping()

Ping Interval to manually ensure an active connection, useful for health chceks. Will return `true` if successful, throw a `NotConnectedError` if there is no active connection, or throw a `TimeoutError` if a response is not received within `pingTimeoutMs`.

async safelyClose()

Safely close the connection to Interval, preventing new actions from being launched and closing the persistent connection afterward. Resolves when the connection is successfully safely closed.

immediatelyClose()

Immediately terminate the connection to interval, terminating any actions currently in progress.

async enqueue(slug, { assignee, params })

Enqueue an action to be completed, with an optional `assignee` email to assign the action to, and optional `params` which will be passed to the action as `ctx.params`. Assigned actions will be displayed in users' dashboards as a task list. See Queued actions for more information.

async (
  slug: string,
  options?: {
    assignee?: string,
    params?: Record<string, string | number | boolean | Date | null | undefined>
  }
) => Promise<{
  id: string;
  assignee?: string;
  params?: Record<string, string | number | boolean | Date | null | undefined>;
}>

async dequeue(queuedActionId)

Dequeue a previously enqueued action which was created with `interval.enqueue()`. See Queued actions for more information.

async (
  queuedActionId: string
) => Promise<void>

async notify(config)

Sends a custom notification to Interval users via email or Slack. To send Slack notifications, you'll need to connect your Slack workspace to the Interval app in your organization settings. See Notifications for more information.

async ({
  message: string,
  title?: string,
  delivery?: {
    to: string;
    method?: 'SLACK' | 'EMAIL';
  }[],
  transactionId?: string,
  idempotencyKey?: string,
}) => Promise<void>

Python

listen()

Synchronously establish the persistent connection to Interval, blocking forever afterward.

async listen_async()

Asynchronously stablish the persistent connection to Interval, not blocking. Should be used alongside something like `asyncio.get_event_loop().run_forever()`.

async ping()

Ping Interval to manually ensure an active connection, useful for health chceks. Will return `True` if successful, raise a `NotConnectedError` if there is no active connection, or raise an `asyncio.TimeoutError` if a response is not received within `ping_timeout`.

async safely_close()

Safely close the connection to Interval, preventing new actions from being launched and closing the persistent connection afterward. Resolves when the connection is successfully safely closed.

async immediately_close()

Immediately terminate the connection to interval, terminating any actions currently in progress.

async enqueue(slug, assignee, params)

Enqueue an action to be completed, with an optional `assignee` email to assign the action to, and optional `params` which will be passed to the action as `ctx.params`. Assigned actions will be displayed in users' dashboards as a task list. See Queued actions for more information.

async (
  slug: str,
  assignee: str | None = None,
  params: dict[str, str | int | float | bool | date | datetime | None] | None = None,
) => QueuedAction

@dataclass
class QueuedAction:
  id: str
  assignee: str | None = None
  params: dict[str, str | int | float | bool | date | datetime | None] | None = None

async dequeue(queued_action_id)

Dequeue a previously enqueued action which was created with `interval.enqueue()`. See Queued actions for more information.

async (
  queued_action_id: str
) => None

async notify(message, title, delivery, transaction_id, idempotency_key)

Sends a custom notification to Interval users via email or Slack. To send Slack notifications, you'll need to connect your Slack workspace to the Interval app in your organization settings. See Notifications for more information.

async (
  message: str,
  title: str | None = None,
  delivery: DeliveryInstruction[],
  transaction_id: str | None = None,
  idempotency_key: str | None = None,
) => None

class DeliveryInstruction(TypedDict):
  to: str
  method: NotRequired["EMAIL" | "SLACK"]

Examples

Safely shutting down a live deployment (blue-green deploys)

TypeScript

Leverage the safelyClose method to ensure there are no service interruptions, lost progress, or malformed data when shutting down a previous version of a live deployment.

src/interval.ts

import path from "path";
import { Interval } from "@interval/sdk";

const interval = new Interval({
  apiKey: "<YOUR API KEY>" // get an API key at https://interval.com/dashboard/develop/keys
  routesDirectory: path.resolve(__dirname, "routes"),
});

interval.listen();

process.on('SIGINT', () => {
  interval
    .safelyClose()
    .then(() => {
      console.log("Safely shut down successfully.");
      process.exit(0);
    })
    .catch(err => {
      console.error(
        "Failed shutting down safely, forcibly closing connection."
      )
      interval.immediatelyClose();
      process.exit(0);
    });
});

JavaScript

Leverage the safelyClose method to ensure there are no service interruptions when shutting down a previous version of a live deployment.

src/interval.ts

const path = require("path");
const { Interval } = require("@interval/sdk");

const interval = new Interval({
  apiKey: "<YOUR API KEY>" // get an API key at https://interval.com/dashboard/develop/keys
  routesDirectory: path.resolve(__dirname, "routes"),
});

interval.listen();

process.on('SIGINT', () => {
  interval
    .safelyClose()
    .then(() => {
      console.log("Safely shut down successfully.");
      process.exit(0);
    })
    .catch(err => {
      console.error(
        "Failed shutting down safely, forcibly closing connection."
      )
      interval.immediatelyClose();
      process.exit(0);
    });
});

Python

Leverage the safely_close method to ensure there are no service interruptions when shutting down a previous version of a live deployment.

import asyncio, os
from interval_sdk import Interval

interval = Interval(
    api_key=os.environ["INTERVAL_API_KEY"],
)

loop = asyncio.get_event_loop()
task = loop.create_task(interval.listen_async())

close_task: asyncio.Task[None] | None = None


async def handle_close_inner():
    try:
        await interval.safely_close()
        print("Safely shut down successfully.")
    except Exception as err:
        print("Failed shutting down safely, forcibly closing connection.", file=sys.stderr)
        await interval.immediately_close()


def stop_loop(fut: asyncio.Future[None]):
    fut.result()
    loop.stop()


def handle_close():
    global close_task

    if close_task is not None:
        return

    close_task = loop.create_task(handle_close_inner())
    close_task.add_done_callback(stop_loop)


loop.add_signal_handler(signal.SIGINT, handle_close)

loop.run_forever()

Did this section clearly explain what you wanted to learn?