deta-space-actions

Deta Space Actions SDK

Setup

Install the SDK via npm:

npm install deta-space-actions

Then import it:

import { Actions } from 'deta-space-actions'

Action Declaration

You can declare actions using the Actions interface of the SDK:

import { Actions } from 'deta-space-actions'

const actions = new Actions()

const action = actions.add({
    name: 'greet',
    title: 'Greet Someone',
    inputs: [
        { name: 'name', type: 'string' }
    ],
    handler: (input) => {
        return `Hello ${input.name}!`;
    }
})

Give your action a name (nees to be lowercase), a title (human readable), optionally define some inputs and then provide a handler function that will be executed with the validated input when the action gets invoked.

You can also use this syntax:

import { createActions } from 'deta-space-actions'

const actions = createActions()

const action = actions.add({
    name: 'greet',
    title: 'Greet Someone',
    inputs: [
       { name: 'name', type: 'string' }
    ],
    handler: (input) => {
        return `Hello ${input.name}!`;
    }
})

Inputs

You can define a input schema for your app action which will allow Space to validate that the inputs being passed to your action match what you are expecting as well as providing hints to clients like Teletype on what input to prompt a user for.

Actions currently support 3 input types:

• string
• number
• boolean

Inputs are defined in an array with each input having a name and a type and can be marked as optional (required by default):

[
    { name: 'name', type: 'string' },
    { name: 'age', type: 'number' },
    { name: 'employed', type: 'boolean', optional: true }
]

To make it easier to define inputs the SDK offers the following helpers:

import { Input, Inputs } from 'deta-space-actions'

const inputs = [
    new Input('name', 'string'),
    Input.create('age', 'number'),
    Inputs('employed').Boolean().Optional(),
    { name: 'name', type: Input.String}
]

TypeScript Support

If you are using TypeScript you can also type the inputs that are being passed to the event handler of an action:

actions.add<{ name: string }>({
    name: 'greet',
    title: 'Greet Someone',
    inputs: [
        Inputs('name').String().Optional()
    ],
    handler: (input) => {
        return `Hello ${input.name}!` // input.name is typed as a string
    }
})

Handling Invocation

There are 3 ways to use the SDK to write actions:

• using the built-in server
• using the Express.js middleware
• hooking into your own server

Using the built-in server

To use the built-in server you need to install Express.js if it's not already installed:

npm install express

After that you can use the built-in server:

import { createActionsServer } from 'deta-space-actions'

const actions = createActionsServer()

actions.add({
    name: 'greet',
    title: 'Greet Someone',
    inputs: [
        { name: 'name', type: 'string' }
    ],
    handler: (input) => {
        return `Hello ${input.name}!`;
    }
})

actions.serve()

Using the Express.js middleware

import { createActions } from 'deta-space-actions'
import express from 'express'

const app = express()
const actions = createActions()

actions.add<{ name: string }>({
    name: 'greet',
    title: 'Greet Someone',
    inputs: [
        { name: 'name', type: 'string' }
    ],
    handler: (input) => {
        return `Hello ${input.name}!`
    }
})

app.use(actions.middleware)

Hooking into your own server

import { createActions } from 'deta-space-actions'
import express from 'express'

const app = express()
const actions = createActions()

const action = actions.add({
    name: 'greet',
    title: 'Greet Someone',
    inputs: [
        { name: 'name', type: 'string' }
    ],
    handler: (input) => {
        return `Hello ${input.name}!`
    }
})

app.post(action.path, (req, res) => {
	const output = action.run(req.body)

	res.send(output)
})

app.get(actions.declarationPath, (req, res) => {
	res.json(actions.declaration())
})

Feedback

This SDK is still in the experimental stage while we are trying to determine a balance between the easiest developer experience and flexibility in integrations. If you have any feedback feel free to hit us up on Discord.